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Preface 


This publication provides information for system programmers about 
MVS/Extended Architecture Data Facility Product, and how to modify and extend 
the data management capabilities of the operating system. 





Organization 
This publication contains the following chapters and appendixes: 


e Chapter 1, “Managing the Volume Table of Contents (VTOC)” on page 1, 
defines and discusses the structure of the VTOC and VTOC index, and the use _ 
of system macros to read a data set control block (DSCB), rename a data set, 
delete a data set from the VTOC, or obtain DASD volume free space 
information. 


e Chapter 2, “Executing Your Own Channel Programs (EXCP)” on page 63, 
defines and discusses the use of the EXCP macro to control the organization of 
data based on device characteristics with your own channel programs. 


e Chapter 3, “Reading from and Writing to Direct Access Devices (XDAP)” on 
page 99, defines and discusses the use of the XDAP macro to read, verify, and 
update blocks without using an access method. | 


e Chapter 4, ‘Password Protecting Data Sets” on page 111, defines and 
discusses system password protection and how to create and maintain the 
PASSWORD data set. 


e The information formerly in Chapter 5, “Exit Routines’ on page 125 has 
been moved to Data Facility Product: Customization. 


e« Chapter 6, “System Macro Instructions” on page 127, defines and discusses 
the system macros used to refer to, validate, and modify system data areas. 


e Chapter 7, ‘Maintaining SYS1.IMAGELIB” on page 203, defines and 
discusses adding a UCS or FCB image to the system image library, and 
maintaining the UCS image tables. 


e Chapter 8, “JES2 Support for the IBM 1403, 3203 Model 5, and 3211 


Printers” on page 225, defines and discusses JES2 support for UCS alias 
names and the 3211 indexing feature. 
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| e The information formerly in Chapter 9, “CATALOG, SCRATCH, and 
| RENAME Dummy Modules” on page 227 has been moved to Data Facility 
| Product: Customization. 





e Chapter 10, “Specifying Buffer Numbers for DASD Data Sets” on page 229, 
defines and discusses the performance considerations when using the BUFNO 
keyword and subparameter. 


e Appendix A, “CVAF VTOC Access Macros” on page 231, defines and 
discusses the format of the VTOC access macros: CVAFDIR, CVAFDSM, 
CVAFFILT, CVAFSEQ, and CVAFTST, and their return codes. 


e Appendix B, “Examples of VTOC Access Macros’ on page 259, defines and 
discusses examples of using the VTOC access macros in your programs. 


e Appendix C, “WTOC Index Error Message and Associated Codes’’ on 
page 297, defines and discusses the error message and field codes issued by 
the Common VTOC Access Facility (CVAF). 
| e The information formerly in Appendix D, “Example of an OPEN Installation 
| Exit Module” on page 305 has been moved to Data Facility Product: 


| Customization. 


e Appendix E, “DFP ISMF Services” on page 307, defines and discusses the 
DFP user services available with ISMF. 


Prerequisite Knowledge 


In order to use this book efficiently, you should be familiar with the following 
topics: 


e Assembler language 
e Standard program linkage conventions 
e The utility programs IEHLIST and IEHPROGM 


« Data management access methods and macro instructions 


Required Publications 


You should be familiar with the information presented in the following 
publications: 


e Assembler H Version 2 Application Programming: Language Reference, 
GC26-4037, and Assembler H Version 2 Application Programming: Guide, 
GC26-4036, contain more information on coding in assembler language. 


¢ MVS/Extended Architecture System Programming Library: Supervisor Services —_ 
and Macro Instructions, GC28-1154, contains a description of standard linkage ry 
conventions. as 
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¢ MVS/Extended Architecture Data Administration: Utilities, GC26-4150, 
describes how to use IEHLIST to maintain the VTOC, and IEHPROGM to 


protect data sets. 


e MVS/Extended Architecture Data Administration Guide, GC26-4140, and 
MVS/Extended Architecture Data Administration: Macro Instruction Reference, 
GC26-4141, contain information on using access methods and macro 
instructions to do input and output. 


Specific prerequisite reading is listed at the beginning of some chapters, as it relates 
to the particular topic. 


Related Publications 


Within the text, references are made to the publications listed in the table below. 


Short Title 
(as it appears 
in the text) 


Access Method 
Services Reference 


Assembler H V2 
Application 
Programming: 
Guide 


Assembler H V2 
Application 
Programming: 
Language 
Reference 


Checkpoint/Restart 
User’s Guide 


Conversion 
Notebook 


Data 
Administration 
Guide 











Publication Title 


MVS/Extended Architecture 
Integrated Catalog 
Administration: Access Method 
Services Reference 


Order Number 


GC26-4135. 


GC26-4136 
MVS/Extended Architecture 
VSAM Catalog Administration: 
Access Method Services Reference 


Assembler H Version 2 SC26-4036 
Application Programming: Guide 

Assembler H Version 2 GC26-4037 
Application Programming: 

Language Reference | 
MVS/Extended Architecture GC26-4139 
Checkpoint/ Restart User’s Guide 

MVS/Extended Architecture GC28-1143 
Conversion Notebook 


MVS/Extended Architecture Data | GC26-4140 
Administration Guide 
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| Short Title 
(as it appears 
in the text) 









Publication Title 
MVS/Extended Architecture Data 


Order Number 
GC26-4141 















Data 


Administration: Administration: Macro 
Macro Instruction Instruction Reference 
Reference 








Data Facility 
Product: 
Customization 


MVS/Extended Architecture Data 
| Facility Product: Version 2 
Customization 


MVS/Extended Architecture 
Debugging Handbook, Volumes 1 
through 5 


GC26-4267 










LC28-1164! 
LC28-1165 
LC28-1166 
LC28-1167 
LC28-1168 


GC35-0033 












Debugging 
Handbook 








Device Support 
Facilities User’s 
Guide and 

Reference 


IBM System/370 
Principles of 
Operation 


IBM 2821 Control IBM 2821 Control Unit 
Unit Component Component Description 
Description 


IBM 3203 Printer IBM 3203 Printer Component 
Component Description and Operator’s Guide 
Description and 

Operator’s Guide 


IBM 3211 Printer, 
3216 


Device Support Facilities User’s 
Guide and Reference 








IBM System/370 Principles of 
Operation 


GA22-7000 





GA24-3312 


GA33-1515 


























IBM 3211 Printer, 3216 
Interchangeable Train Cartridge, 


GA24-3543 









Interchangeable and 3811 Printer Control Unit 
Train Cartridge, Component Description and 
and 3811 Printer Operator’s Guide 

Control Unit 

Component 


Description and 
Operator’s Guide 


IBM 3262 Printer 
Model 5 Product 
Description 










IBM 3262 Printer Model 5 
Product Description 


GA24-3936 


Note: 


1 All five volumes may be ordered under one order number, LBOF-1015. 
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Z Short Title 
( | (as it appears 

- in the text) _ Publication Title Order Number 
IBM 3800 Printing IBM 3800 Printing Subsystem GC26-3846 
Subsystem Programmer’s Guide 
Programmer’s 
Guide 
IBM 4245 Printer IBM 4245 Printer Model 1 | GA33-1541 
Model 1 Component Description and | 
Component Operator’s Guide 
Description and | 
Operator’s Guide 


IBM 4248 Printer IBM 4248 Printer Description GA24-3927 

Description | 

Initialization and MVS/Extended Architecture GC28-1149 

Tuning System Programming Library: | 
Initialization and Tuning 

JCL User’s Guide MVS/Extended Architecture JCL | GC28-1351 | 
User’s Guide ee ee 

JCL Reference MVS/Extended Architecture JCL ~ |'GC28-1352 




















Reference 


JES2 Initialization MVS /Extended Architecture SC23-0065 
ee and Tuning System Programming Library: 
{ JES2 Initialization and Tuning 
JES3 Data Areas MVS/Extended Architecture Data \| LYB8-1195 
| Areas (MVS/JES3) 









JES3 Initialization MVS/ Extended Architecture S$C23-0059 

| and Tuning System Programming Library: 
JES3 Initialization and Tuning | 

Linkage Editor and MVS/Extended Architecture GC26-4143 

Loader User’s Linkage Editor and Loader User’s 

Guide Guide 

Magnetic Tape MVS/Extended Architecture GC26-4145 

Labels and File Magnetic Tape Labels and File 

Structure Structure Administration 

Administration 


Open/Close/EOV MVS/Extended Architecture LY26-3966 
Logic Open/Close/EOV Logic 


RACE General Resource Access Control Facility GC28-0722 





Information (RACF): General Information 
Manual 
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Short Title | | ~ 
(as it appears | ‘eo 
in the text) Publication Title | Order Number 

Service Aids MVS/Extended Architecture GC28-1159 


System Programming Library: 
GC28-1154 












Service Aids 


MVS/Extended Architecture 
System Programming Library: 
Supervisor Services and Macro 
Instructions 


System Generation | MVS/Extended Architecture GC26-4148 
| Installation: System Generation 


System Logic | MVS/Extended Architecture LY28-1234 (Part 
Library System Logic Library: Volume 8 1) 

of 17, Parts 1 and 2 (IOS) LY28-1235 (Part 
2) 


GC28-1150 
GC28-1151 











Supervisor Services 
and Macro 
Instructions 





System Macros and MVS/Extended Architecture 

Facilities System Programming Library: 
System Macros and Facilities, 
Volumes 1 and 2 









GC28-1376 
GC28-1377 


System Messages MVS/ Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 < 


TSO Command MVS Extended Architecture TSO GC28-0646 ey 
Language Command Language Reference 
Reference (OS/VS2 TSO Command 
Language Reference, as updated | 
by Supplement SD23-0259 for 
MVS/XA) 
TSO/E Data Areas MVS/Extended Architecture | LYB8-1119 
TSO/E Data Areas (plus 
Utilities MVS/Extended Architecture Data | GC26-4150 _ | 
Administration: Utilities 


Supplement LDB3-0276) 
VSAM MVS/Extended Architecture GC26-4152 
Administration: VSAM Administration: Macro 
Macro Instruction | Instruction Reference 
Reference 












Vili MVS/XA System—Data Administration 











Notational Conventions 





A uniform system of notation describes the format of data management macro 
instructions. This notation is not part of the language; it simply provides a basis for 
describing the structure of the commands. 

The command format illustrations in this book use the following conventions: 


¢« Brackets [ ] indicate an optional parameter. 


e Braces }} indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 


e Items separated by a vertical bar (|) represent alternative items. No more 
than one of these items may be selected. 





e Anellipsis (...) indicates that multiple entries of the type immediately preceding 
the ellipsis are allowed. 





¢ Other punctuation (such as parentheses, commas, and spaces) must be entered 
as shown. A space is indicated by a blank. 


e BOLDFACE type indicates the exact characters to be entered, except as 
described in the bullets above. Such items must be entered exactly as 
illustrated. 


( o e Lowercase italic type specifies fields to be supplied by the user. 


e BOLDFACE UNDERSCORED type indicates a default option. If the 
parameter is omitted, the underscored value is assumed. 


e Parentheses ( ) must enclose subfields if more than one is specified. If only 
one subfield is specified, you may omit the parentheses. 


Address and Register Conventions 


The following describes the meaning of each notation used to show how an 
operand can be coded: 


symbol 
The operand can be any valid assembler-language symbol. 

(0) 
General register 0 can be used as an operand. When used as an operand in a 
macro instruction, the register must be specified as the decimal digit O 
enclosed in parentheses as shown above. 

(7) 


General register 1 can be used as an operand. When used as an operand in a 
macro instruction, the register must be specified as the decimal digit 1 
enclosed in parentheses as shown above. When you use register 1, the 
instruction that loads it is not included in the macro expansion. 
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(2-12) 
The operand specified can be any of the general registers 2 through 12. All 
registers as operands must be coded in parentheses; for example, if register 3 
is coded, it is coded as (3). When one of the registers 2 through 12 is used, it 
can be coded as a decimal digit, symbol (equated to a decimal digit), or an 
expression that results in a value of 2 through 12. 


RX-Type Address 
The operand can be specified as any valid assembler-language RX-type 
address. The following shows examples of each valid RX-type address: 


Name Operation Operand 

ALPHA1 is 1,39(4,10) 

ALPHA2 L REG1,39(4,TEN) 
BETAI L 2,ZETA(4) 

BETA2 L REG2,ZETA(REG4) 
GAMMAI1 L 2,ZETA 

GAMMA2 L REG2,ZETA 
GAMMA3 L 2,=F’1000’ 
LAMBDAI L 3,20(,5) 


Both ALPHA instructions specify explicit addresses; REG1 and TEN have 
been defined as absolute symbols. Both BETA instructions specify implied 
addresses, and both use index registers. Indexing is omitted from the 
GAMMA instructions. GAMMA1 and GAMMA2 specify implied 
addresses. The second operand of GAMMAS3 is a literal. LAMBDA1 
specifies an explicit address with no indexing. 


A-Type Address 
The operand can be specified as any address that can be written as a valid 
assembler-language A-type address constant. An A-type address constant 
can be written as an absolute value, a relocatable symbol, or relocatable 
expression. Operands that require an A-type address are inserted into an 
A-type address constant during the macro expansion process. For more 
details about A-type address constants, see Assembler H Version 2 
Application Programming: Language Reference. 


absexp 
The operand can be an absolute value or expression. An absolute expression 
can be an absolute term or an arithmetic combination of absolute terms. An 
absolute term can be a nonrelocatable symbol, a self-defining term, or the 
length attribute reference. For more details about absolute expressions, see 
Assembler H Version 2 Application Programming: Language Reference. 
OS/VS—DOS/VSE—VM/370 Assembler Language. 


relexp 
The operand can be a relocatable symbol or expression. A relocatable 
symbol or expression is one whose value changes by n if the program where 
it appears is relocated n bytes away from its originally assigned area of 
storage. For more details about relocatable symbols and expressions, see 
Assembler H Version 2 Application Programming: Language Reference. 
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Summary of Changes 





| Release 3.0, June 1987 





| Enhancements and New Support 


| Data sets may now be retained beyond the year 1999 or be retained indefinitely 
| (never-scratch). ‘Deleting a Data Set from the VTOC (SCRATCH and CAMLST 
| SCRATCH)” on page 33 describes never-scratch designations. 


Information about the new LSPACE macro instruction has been added. 

Chapter 1, “Managing the Volume Table of Contents (VTOC)” on page 1, 
explains how to use the LSPACE macro to determine the amount of free space and 
the degree of space fragmentation on a direct access volume. The LSPACE macro 
also allows you to obtain VTOC status information. 


Open, Close, and End-of-Volume parameter lists may now reside at an address 
above 16 megabytes. Chapter 2, “Executing Your Own Channel Programs 
(EXCP)” on page 63 explains the changes to the EOV macro format and 
description in support of parameter lists above 16 megabytes. 


The retrieval area for information extracted from a JFCB can now be allocated at 
an address above 16 megabytes. Chapter 6, “System Macro Instructions” on 

- page 127 now includes the following information in support of the retrieval area 
above 16 megabytes. 


| e The differences in the RDJFCB and OPEN macro operands and parameter 
| lists. 


| « The new X'13' exit list entry code. 
| e The use of the IHAARL macro. 


Information related to customizing the Data Facility Product for individual users 
has been moved to Data Facility Product: Customization, a new book. This includes 
the information in Chapter 2 under “‘Appendages’”’ on page 71, all of Chapter 5 
(including the new information about the conventions that installation-written 
DADSM preprocessing and postprocessing modules must follow for 31-bit versus 
24-bit addressing), all of Chapter 9, and the example formerly in Appendix D. 





Summary of Changes XI 


Service changes have been made throughout the manual, and are indicated in the 
text by revision bars. 


Release 2.0, June 1986 


Enhancements and New Support 
Information has been added for support of CVAF Filter Services. 


e The format of the CVPL in Chapter 1, “Managing the Volume Table of 
Contents,” has been updated. 


e Appendix A now contains the CVAFFILT macro syntax and explains the 
parameters, register contents, and return codes. 


¢ Appendix B now contains an example of a CVAFFILT invocation. 

Information has been added for support of DASD Calculation Services. 

e Chapter 5, “Exit Routines,” describes the use of the DASD Calculation 
Services precalculation and postcalculation installation exits. It also explains 


the parameters, register contents, and return codes. 


Appendix E has been added to provide interface information for DFP/ISMF | | 
services. ed 


Chapter 1, “Managing the Volume Table of Contents,” has been reorganized and 
rewritten. 


Chapter 7, “Maintaining SYS1.IMAGELIB,” has been reorganized and rewritten. 


Service changes have been made throughout the manual, and are indicated in the 
text by revision bars. 


Release 1.0, April 1985 


Enhancements and New Support 


The SCRATCH and CAMLST SCRATCH macro descriptions have been updated 
to include support for the erasure of residual DASD data. 


Information has been added to the description of the REALLOC macro for 
DADSM support of DFDSS that: 


e Describes the new support and explains what it does. 





e Adds new keywords. 
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e Adds new return codes. 

The PARTREL macro has been added to the partial release section that: 

e Describes the new support and explains what it does. 

e Adds all keywords and descriptions. 

e Adds new return codes. 

Information supporting the ERASE-ON-SCRATCH option for RACF-defined 


data sets has been added to “Deleting a Data Set from the VTOC (SCRATCH and 
CAMLST SCRATCH)” on page 33. 





Information has been added to Figure 29 on page 134 to support the: : 
e 3262 Model 5 Printer. 


e 4245 Printer. 





e 4248 Printer. 
Information has been added to support the IBM 3380 (all models). 


The following IBM 3480 Magnetic Tape Subsystem support information has been 
added: 


e The high-speed positioning feature. 
e Chapter 6, “System Macro Instructions” on page 127, has been updated. 


e The MSGDISP macro has been added to permit loading a message display on 
the 3480. 


e The 3480 has been added to Figure 29 on page 134. 


Summary of Changes Xill 


“High-Speed IBM 3480 Positioning” on page 149 in Chapter 6, “System Macro 
Instructions” on page 127 has been added and describes how to set the tape block 
ID for the IBM 3480 Magnetic Tape Subsystem in full function mode. 


Chapter 1, formerly titled ‘““Controlling Space on DASD Volumes,” has been 
renamed, “Managing the Volume Table of Contents (VTOC).” 


Version 2 Publications 


The Preface includes new order numbers for Version 2. 
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Chapter 1. Managing the Volume Table of Contents (VTOC) 


The VTOC 





The direct access device storage management (DADSM) routines control allocation 
of space on direct access volumes through the volume table of contents (VTOC) of 
that volume, and through the VTOC index if one exists. This chapter gives an 
overview of the VTOC and the VTOC index and discusses how to use system 
macros to access the VTOC and VTOC index. 


The VTOC is a data set on a direct access volume that describes the contents of 
that volume. It resides in a single extent (that is, it is a continuous data set) 
anywhere on the volume after cylinder 0, track 0. Its address is located in the 
VOLVTOC field of the standard volume label (see Figure 1 on page 2). 
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Standard Volume Label 





11(B) 
VOLVTOC (10 bytes) 
CCHHR of first 
record in VTOC 
\ / 
\ | a 
\ / 
\ / 
\ / 
\ / 
\ ‘ V4 
\ J / 
CylinderO \ J 
Track 0 


Record Record | Record 
1 7 3 


VTOC Data Set 
(Can be located anywhere 


Record on the volume after 
\ ee Record e cylinder 0, track 0.) 
3 


Figure 1. Locating the Volume Table of Contents (VTOC) 


The VTOC is composed of 140-byte! data set control blocks (DSCBs) that 
correspond either to a data set or VSAM data space currently residing on the 


volume, or to contiguous, unassigned tracks on the volume. DSCBs for data sets or | 


data spaces describe their characteristics. DSCBs for contiguous, unassigned tracks 
indicate their location. 


1 The 140 bytes are defined as a 44-byte key portion followed by a 96-byte data 
portion. You may make references to the logical 140-byte DSCB or to either of its 
parts. 7 
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Data Set Control Block (DSCB) Format Types 


Format-0 DSCB 





The VTOC has seven different kinds of DSCBs. This section lists the different 
kinds of DSCBs, what they are used for, how many exist on a volume, and how 
they are found. 


The first record in every VTOC is the VTOC (format-4) DSCB that describes (1) 
the device that the volume resides on, (2) the attributes of the volume itself, and 
(3) the size and contents of the VTOC data set itself. 


The format-4 DSCB is followed by a free-space (format-5) DSCB that, for a 
nonindexed VTOC, lists the extents on the volume that have not been allocated to 
a data set or VSAM data space. Each format-5 DSCB contains 26 extents. If 
there are more than 26 available extents on the volume, another format-5 DSCB 
will be built for every 26 extents. The format-5 DSCBs are chained, using the last 
field of each format-5 DSCB. An indexed VTOC does not use format-5 DSCBs 
for describing free space; however, one empty format-5 DSCB is provided to allow 
a basis for converting back to a nonindexed VTOC. 


The third and subsequent DSCBs in the VTOC have no prescribed sequence. 


A data set or VSAM data space is defined by one or more DSCBs in the VTOC of 
each volume on which it resides. The number of DSCBs needed to define a data 
set or VSAM data space is determined by (1) the organization of the data set 
(ISAM data sets need a format-2 DSCB to describe the index) and (2) the number 
of extents the data set or VSAM data space occupies (a format-3 DSCB is needed 
to describe the 4th through the 16th extents; additional format-3 DSCBs may be 
required to describe the extents for a VSAM data set cataloged in an Integrated 
Catalog Facility catalog). Figure 2 on page 7 shows the general makeup of a 
VTOC and the DSCBs needed to define two types of data sets (ISAM and 
non-ISAM). 


Data set A (in Figure 2 on page 7) is an ISAM data set; three DSCBs, a format-1, 
format-2, and format-3, are identified. Data sets B, C, and D could be sequential, 
partitioned, or direct data sets or they could be VSAM data spaces. Data set B has 
more than three extents and therefore requires both a format-1 and a format-3 
DSCB. 


Data sets C and D have three or fewer extents and need only a format-1 DSCB. 
The format-6 DSCB, pointed to by the format-4 DSCB, is used to keep track of 
the extents allocated in order to be shared by two or more data sets (split-cylinder 
data sets). For example, if data sets C and D share an extent made up of one or 
more cylinders, this extent would be described in the format-6 DSCB. Note that 
split-cylinder data sets cannot be allocated, but existing split-cylinder data sets can 
still be processed. 


Name: Free VTOC Record 


Function: Describes an unused record in the VTOC (contains 140 bytes of binary 
zeros). To delete a DSCB from the VTOC, a format-0 DSCB is written over it. 
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Format-1 DSCB 


Format-2 DSCB 


Format-3 DSCB 





How Many: One for every unused 140-byte record on the VTOC. The 
DS4DSREC field of the format-4 DSCB is a count of the number of format-0 
DSCBs on the VTOC. This field is not maintained for an indexed VTOC. 


How Found: Search on key equal to X'00' (sometimes X'00000000') for a 
nonindexed VTOC; for an indexed VTOC, the VTOC map of DSCBs is used to 
find a format-O DSCB. : 


Name: Identifier 
Function: Describes the first three extents of a data set or VSAM data space. 


How Many: One for every data set or data space on the volume, except the 
VTOC. 


How Found: Search on key equal to the data set name. For an indexed VTOC, a 
CCHHR pointer for each data set name is in the VTOC index. 


Name: Index 
Function: Describes the indexes of an ISAM data set. 


How Many: One for every ISAM data set (for a multivolume ISAM data set, a 
format-2 DSCB exists only on the first volume). 


How Found: Chained from a format-1 DSCB that represents the data set. 


Name: Extension 


Function: Describes the 4th through 16th extents of a data set or VSAM data 
space. Data sets and VSAM data spaces are restricted to 16 extents per volume. 
VSAM data sets cataloged in an Integrated Catalog Facility catalog may be 
extended to a maximum of 123 extents, in which case there may be as many as ten 
format-3 DSCBs. 


How Many: One for each data set or VSAM data space on the volume that has 
more than three extents. There may be as many as ten for a VSAM data set 
cataloged in an Integrated Catalog Facility catalog. 


How Found: Chained from a format-2 or a format-1 DSCB that represents the 
data set or VSAM data space. In the case of a VSAM data set cataloged in an 
Integrated Catalog Facility catalog, the chain may be from a preceding format-3 
DSCB. 
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Format-4 DSCB 


Format-5 DSCB 


Format-6 DSCB 


Name: VTOC 


Function: Describes the extent and contents of the VTOC and provides volume 
and device characteristics. If the VITOC is indexed, certain fields of this DSCB are 
not maintained by DADSM. See “Structure of an Indexed VTOC.” 


How Many: One on each volume. 


How Found: VOLVTOC field of the standard volume label contains its address. It 
is always the first record in the VTOC. 


Name: Free Space 


Function: On a nonindexed VTOC, describes the space on a volume that has not 
been allocated to a data set or to a VSAM data space (available space). For an 
indexed VTOC, format-S is zero, and the volume pack space map describes the 
available space. 


How Many: One for every 26 noncontiguous extents of available space on the 
volume for a nonindexed VTOC; for an indexed VTOC, there is only one. 


How Found: The first format-5 DSCB on the volume is always the second DSCB 
of the VTOC. If there is more than one format-5 DSCB, it will be chained from 
the previous format-5 DSCB via the DSSPTRDS field of each format-5 DSCB. 


Name: Shared Extent 


Function: Describes the extents shared by two or more data sets (split-cylinder 
extents). 


How Many: One for every 26 split-cylinder extents on the VTOC. 


How Found: The address of the first format-6 DSCB is contained in the 
DS4F6PTR field of the format-4 DSCB. If there is more than one format-6 DSCB 
on the volume, it will be chained from the previous format-6 DSCB via the 
DS6PTRDS field of the format-6 DSCB. 


Allocating and Releasing DASD Space 


The DADSM allocate and extend routines assign tracks and cylinders on direct 
access volumes for new data sets and VSAM data spaces. The DADSM extend 
routine obtains additional space for a data set or VSAM data space that has already 
exceeded its original, primary allocation. The DADSM scratch and partial release 
routines are used to release space that is no longer needed on a direct access 
volume. 


The DADSM routines allocate and release space by adding, deleting, and 
modifying the DSCBs. When space is needed on a volume, the allocate routines 
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search the appropriate DSCBs for enough contiguous, available tracks to satisfy the 
request. If there are not enough contiguous tracks, the request is filled, using as 
many as five noncontiguous groups of free tracks. The appropriate DSCBs are 
modified to reflect the assignment of the tracks. 


When space is released, the scratch routines free the DSCBs of the deleted data set 
or data space. For a nonindexed VTOC, to indicate that the tracks containing the 
affected data set or data space can be reallocated, a free space (format-5) DSCB is 
built (or modified if existent). For an indexed VTOC, the index is updated. 
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( Standard Volume Label 


11(B) 
VOLVTOC 





field 


VTOC Data Set 


Data Set A | Data Set B 
: DSCR Format-1 DSCBY/ 


! Description of 
the data set ay 
its first 3 estenty 


Format-4 DSCB First FS DSCB 


Description of Description of 
device, volume, 26 available 
and the VTOC extents 

extent 






Data Set C 


Format-6 DSCB Next F5 DSCB 


Description of Description of V Description of : 


as many as 26 as many as 26 data set C and 
shared-cylinder available exents its first 3 extents 
Y 








es. Data Set D 
( : (ZFormat-1 DSCB7/ 


Description of 
the data set and 


its first 3 yyy 
BSS cosh : Yj) 















DSCB for a non-ISAM 
data set (Data Sets B, C, D) 
or a VSAM data space 


| DSCB for an ISAM 
| data set (Data Set A) 





Note: Empty boxes in the VTOC data set represent free VTOC Records (Format-0 DSCBs) 


Figure 2. Contents of VTOC—DSCBs Describing Data Sets 








Chapter 1. Managing the Volume Table of Contents (VTOC) 7 


a rrennmmm memes moans Sata A WAI me eb Seen oe eee eee cue ne omy Sage omnes nig EE Does! <2 URETTT LTT STR MEMES He VEE AMIN 2 ee hee ee te nee 





The VTOC Index 


The VTOC index is a physical-sequential data set, residing on the same volume as 
the VTOC. It contains an index of data set names of format-1 DSCBs in the 
VTOC and free space information. The index is searched instead of the hardware 
keys. 


The VTOC index is optional. You may build it when you initialize the volume, or 
for an existing VTOC (with the volume online or offline). You may subsequently 
inactivate it (online or offline) so that the VTOC is processed without using the 
index. 


Each VTOC index is formatted by Device Support Facilities with physical blocks 
2048 bytes in length. These physical blocks are the VTOC index records (VIRs), 
the basic structural units of the index. The kind of information they contain 
depends on the part of the index they belong to. 


Several different kinds of records, each built from one or more VIRs, are in a 
VTOC index: 


e The VTOC index entry record (VIER) that is used to access format-1 DSCBs 
and the format-4 DSCB 


e The VTOC pack space map (VPSM) that shows what space has been allocated 
on a disk pack 


e The VTOC index map (VIXM) that shows which VIRs have been allocated in 
the VTOC index 


e The VTOC map of DSCBs (VMDS) that shows which DSCBs have been 
allocated in the VTOC 


An Example of a VTOC and Its Index 


A format-1 DSCB in the VTOC contains the name and extent information of the 
VTOC index. The name of the index must be 'SYS1.VTOCIX.xxxxxxxx', where 
"xxxxxxxx! can be anything valid in a data set name and is generally the serial 
number of the volume containing the VTOC and its index. The name must be 
unique within the system to avoid ENQ contention. The relationship of a VTOC 
to its index is shown in Figure 3 on page 9. Each of the components of the index 
is discussed separately in the following sections. 
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VTOC VTOC Index 


Format—4 DSCB 
Format—5 DSCB 


Other DSCBs 


Format—1 DSCB for the VTOC 
Index: SYS1.VTOCIX.nnn 


Other DSCBs 


Figure 3. Relationship of a VTOC to Its Index 











The VTOC Index Entry Record (VIER) 


VIERs have these characteristics: 


~ e A VIER uses one VIR and contains variable-length index entries. The number 
( of VIERs in an index varies depending upon the number of data sets on the 
volume. 


e VIERs in a VTOC index may be on one or many levels. All index entries in a 
VIER are at the same index level. VIERs have a hierarchic relationship. Index 
entries in higher-level VIERs point to lower-level VIERs. Index entries in 
level-one VIERs (those at the lowest level) point to format-1 DSCBs for data 
sets on the volume. 


e A higher-level VIER is created when the fourth lower-level VIER is created. 
When that new higher-level VIER is filled with pointers to lower-level VIERs, 
a new VIER at the same level is created. Again, when the fourth VIER at the 
same level is created, a VIER at a still higher level is created, adding another 
level to the index. 


Contents of VIER Fields 
Each VIER contains a header and sections (see Figure 4 on page 10). The VIER 
header contains: 
e A field identifying the VTOC index record as a VIER. 
e« The relative byte address (RBA) of the VIER. 
a e A pointer to a VIER at the same level (hence, a “horizontal” pointer). The 
( VIER pointed to contains index entries whose Keys are greater than any key in 
the pointing VIER. 
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e The level number (LVL) of this VIER. 


e The number (SECNO) of sections (a VIER contains eight sections). 


e The length (SECL) of the sections (each section is 246 bytes in length). 


e The offsets to the first-used and the last-used sections. 


e The 44-byte high key of the VIER. 


Each section contains: 


« Anoffset to the last entry in the section (or zero if the section is empty) 


e Index entries 


0(00) 
4(04) 
8 (08) 
12(0C) 
16( 10) 
20( 14) 
24( 18) 
28(1C) 
32(20) 
76(4C) 














EBCDIC Characters VIER 


RBA of This VIER 


PTRL 


barARontal Bainter: 


| Old Horizontal Pointer 


SECNO | SECL 


[Hitest Key in Tis WR 


Figure 4. Format of the VIOC Index Entry Record (VIER) 
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Header 
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Index Entries 


Format of a VTOC Index Entry 





The format of an index entry is: 


NAME OFFSET BYTES DESCRIPTION 

VXEFLG 00(00) 1 Flag byte 

VXEKEYL o1(01) 1 Length of the VXEKEY field 
VXEFC 02(02) 1 Unused 

VXERPTR 03(03) 4oor 5 Record pointer 

VXEKEY 07(07) 1 to 44 Name of a data set, if a 


or level—one VIER; if not, the 
08(08) high key in the header of a 
lower—level VIER 








Each index entry contains: 
¢« A flag byte. | 


« Akeylength field (containing a value of 1 to 44, depending on the length of the 
data set name). 





¢ Arecord pointer (VXERPTR) that is one of the following: 


a — In level-one VIERs, the 5-byte CCHHR of the format-1 or format-4 
( ; DSCB that represents the data set whose name is the key in the entry 


— In other VIERs, the 4-byte RBA of the lower-level VIER whose high key 
is the key in the entry 


e A key that, for level 1 VIERS, is the data set name, and for level 2 or higher 
VIERs is the high key of a lower-level VIER. Trailing blanks are suppressed in 
the VTOC index entry. 

When a VIER Is Created 

The first level-one VIER is created when the VTOC index is created. Subsequent 

VIERs are created when a data set name is to be added to the VTOC index but the 

VIER where it should be added is full. A new VIER is created in the following 

manner: 


e« A new VIER is allocated. 


e Half of the sections from a full VIER (those containing the highest keys) are 
moved into the new VIER, leaving each VIER half empty. 


e The new index entry is added to one of the two VIERs, depending on its key. 
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A Tree of Linked VIERs 


Figure 5 on page 13 shows how VIERS are related to each other. Note that the 
VIERs (which are simplified here—only the high key is shown in the header) form 
a type of “‘tree structure.” 


How to Find a Format-1 DSCB 


In the search for the format-1 DSCB for a particular data set, one path along the 
tree structure is followed. 


As seen in Figure 4 on page 10, a field in the header of a VIER contains the 
highest key of any index entry in that VIER. Beginning with this field in the first 
high-level VIER, the following search logic is used: Is the key of the data set (the 
data set name) lower than or equal to the VIER’s high key? If neither, the test is 
again applied with the VIER having a greater high key pointed to by the horizontal 
pointer. This procedure continues until a VIER is found having a high key that is 
greater than or equal to the key of the data set. Comparisons are then made with 
the entries in the VIER’s sections. Eventually, an entry is found with a key greater 
than or equal to the data set key. This entry points to a VIER at the next-lower 
level. 


The search proceeds to successively lower levels until an entry in a level-two VIER 
is found whose key is greater than or equal to the key of the data set. This entry 
points to a level-one VIER that, in turn, contains an entry with a key that is equal 
to the data set key and that points to the format-1 DSCB for the desired data set. 


Special Cases in a DSCB Search 


If there is only one level in the VTOC index, the entries in the VIERs all point to 
format-1 DSCBs, so that only one level need be searched. 


If an update to the VTOC index requires a new VIER and the update is interrupted 
(for example, because of an I/O error or a system failure), the entry in the level-n 
VIER may contain a key that is greater than the high key in the lower-level VIER 
pointed to by that entry. In this case, two VIERs at level n-1 may have to be 
searched. This situation is corrected when DADSM next processes the volume. 


The VTOC Pack Space Map (VPSM) 


The VPSM accounts for space on a disk pack. It shows what space on the volume 
has been allocated and what space remains free. 


The map contains bit maps of the cylinders and tracks on the volume. A value of 
one indicates that the cylinder or track has been allocated; a value of zero, that it 
has not been allocated. The bit representing a cylinder is set to zero if no tracks on 
the cylinder have been allocated; it is set to one if any track has been allocated. 
Tracks assigned as alternate tracks are marked as allocated. 


The VPSM replaces the chain of format-5 DSCBs, but one empty format-5 DSCB 


is left in the VTOC to allow for conversion back to a nonindexed VTOC, a process 
that requires reconstruction of a format-5 DSCB chain. 
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SYS1.MACLIB 
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B41103.TEST M32107.LIB 
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SYS1.VTOCIX.A 







- 
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Format-4 OSCB in the VTCC 


Figure 5. Structure of Linked VIERs 





The format of an index map (including the VPSM) is shown in Figure 6 on 
page 14. 
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Large Unit Map 
(VTOC Pack Space Map Only) 


Small Unit Map 
VTOC Recording Facility Data 
(VTOC Index Map Only) 


Figure 6. An Index Map 


The VTOC Index Map (VIXM) 


The VIXM contains a bit map in which each bit represents one VTOC index record 
(VIR). The status of the bit indicates whether the VIR is allocated (1) or 
unallocated (0). 


An area of the VIXM is reserved for VTOC recording facility (VRF) data. (This is 


the facility that allows detection of and recovery from certain errors in an indexed 
VTOC.) 


A field in the first VIXM record points to the first high-level VIER. Another field 
in the first VIXM record (VIR in Figure 7 on page 15) contains the number of 
VTOC index records that contain all the space maps. 
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The VITOC Map of DSCBs (VMDS) 


The VMDS contains a bit map where each bit represents one DSCB in the VTOC. 
The status of the bit indicates whether the DSCB is allocated (1) or unallocated 


(0). 


Name 


VIMAP 
VIMH 


VIMID 


VIMRBA 


VIMHZPTR 


VIMORG 


VIMVRFDA 


VIMVRFO 


VIMFLG1 


VIMVRFSW 


VIMLUF1 


VIMLUOF 


VIMLUSZ 


Figure 7 (Part 1 of 2). 


Offset Bytes Description 

00O(X'00') 2048 VTOC map 

OOCX'00') 44 VTOC map header 

OO(X'00') 4 Map ID in EBCDIC ('VPSM', 
'VIXM!', or 'VMDS') 

04(X'04') 4 RBA of this map 

O8(X'08') 4 Horizontal RBA pointer to next VIR 
of this map 

12(X'0C') 4 Sequence number of the first entry in 
the map 

16(X'10') 2 Offset to current VRF data (if 
VIMVRFSW= 1) or offset where VRF 
data may be written (if 
VIMVRFSW=0), (first VIXM only) 

18(X'12') 2 Offset to VRF area (first VIXM VIR 
only) 

20(X'14') 1 Flag byte 

X'80' VRF data exists if 1 
.XXX XXXX Reserved 

21(X'15') 1 Large unit flag byte 

22(X'16') 2 Offset into VIR of large unit map 
(zero if none) 

24(X'18') 4 Size in bits of large unit map 

Format of a VTOC Map 
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Name Offset Bytes Description | —_ 
i 
VIMSUF1 28(X'1C') 1 Small unit flag byte 
VIMSUBIT 29(X'1D') 1 Number of small unit bits per large 
- unit (zero if none) 
VIMSUOF 30(X'1E') 2 Offset into VIR of small unit map 
VIMSUSZ 32(X'20') 4 Size in bits of small unit map 
36(X'24') 3 Reserved 
VIMVIR 39(X'27') 1 Number of map records (VIXM only) 
VIMFHLV 40(X'28') 4 RBA of first high-level VIER (VIXM 
only) 
VIMLUMAP 44(X'!2C') kk Large unit map (kk is VIMLUSZ/8, 
rounded up) 
VIMSUMAP mm nn Small unit map (mm is VIMSUOF, nn 
is VIMSUSZ/8, rounded up) 
VIMVRF pp aq VRE area (pp is VIMVRFO, qq is 
remainder of first VIXM) 
ene | 
Figure 7 (Part 2 of 2). Format of a VTOC Map 


Structure of an Indexed VTOC 


An indexed VTOC is identical to a nonindexed VTOC, except that, for an indexed 
VTOC, only a single format-5 DSCB exists and is empty, and certain format-4 
DSCB data (the number of format-O DSCBs and the CCHHR of the highest 
format-1 DSCB) is not maintained by DADSM. The DOS bit (bit 0 in field 
DS4VTOCI), set to one in the format-4 DSCB, indicates that these fields (and the 
format-5 DSCB) cannot be relied on. The index bit (bit 7 in field DS4VTOCI) is 
set in the format-4 DSCB; it indicates that a VTOC index exists. 


Scratch/Rename/ Allocate Restrictions 


A VTOC index data set may not be scratched if the VTOC index is active. Neither 
may a VTOC index data set be renamed if the VTOC index is active, unless it is 
being renamed to another name beginning with 'SYS1.VTOCIX.'. A data set may 
not be renamed to a name beginning with 'SYS1.VTOCIX.' if there is already such 
a data set on the volume. Only one data set whose name begins with 
'SYS1.VTOCIX.' may be allocated on a volume. 
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Initializing and Maintaining the VTOC 





Creating the VTOC and VTOC Index 


To prepare a volume for use (to initialize it), the Device Support Facilities utility is 
used. One of the things this utility does is to build the VTOC. After initialization, 
this VTOC will contain a format-4 DSCB and a format-5 DSCB. Fora 
nonindexed VTOC, the format-5 DSCB contains an extent entry for all the free 
space on the volume; the initial number of extents in the format-5 DSCB is one or 
two, depending on where the VTOC is located on the volume. If the VTOC is 
located somewhere other than at the beginning or end of the volume, two extent 
entries are needed to describe the free space that precedes and follows it. For an 
indexed VTOC, the format-5 DSCB contains a zero. 











A VTOC index can be created when a volume is initialized by using the Device 
Support Facilities command INIT and specifying the INDEX key word. 


A nonindexed VTOC can be converted to an indexed VTOC by using the 
command BUILDIX and specifying the IXWTOC keyword. The reverse is also 
possible by using the BUILDIX command and specifying the OSVTOC keyword. 


For more detailed information, see Device Support Facilities User’s Guide and 
Reference. 


( Protecting the VTOC and VTOC Index 


Resource Access Control Facility (RACF) 
You can protect the VTOC and VTOC index by using the Resource Access 
Control Facility (RACF). This is done by defining the volume serial entity under 
the RACF class DASDVOL. A user must be authorized to the 
DASDVOL/Vvolume serial entity at the following levels: 
e At the UPDATE level, to open the VTOC for output processing. 


e At the UPDATE level, to open for output processing any data set whose name 
begins with 'SYS1.VTOCIX.'. 


e At the ALTER level, to allocate, rename, or scratch any data set whose name 
begins with 'SYS1.VTOCIX.'. 


e At the ALTER level, to rename a data set to any name that begins with 
'SYS1.VTOCIX.'. 


Neither the VTOC nor the VTOC index is protected from being opened for input 
processing by the DASDVOL/Vvolume serial entity. 


Note that neither the VTOC nor the VTOC index can be protected through the 
( : RACF class DATASET. 
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Authorized Program Facility (APF) Requirements 


A program must be authorized by the authorized program facility (APF) to 
perform any of the following functions: 


Password Protection 


Opening a VTOC for output processing 


Opening for output processing a data set whose name begins with 
'SYS1.VTOCIX.' 


Allocating, renaming, or scratching any data set whose name begins. with 
'SYS1.VTOCIX.' 


Renaming a data set to any name that begins with 'SYS1.VTOCIX.' 


The VTOC index data set may be password protected. The protection is the same 
as for any password-protected data set. Password checking is bypassed if the 
volume in which the VTOC index resides is protected by RACF through the 
DASDVOL class. 


Copying/Restoring/Initializing the VTOC 


Operations on Volumes Containing a Nonindexed VTOC 


Restoring a Volume from a Dump Tape. There are no operational requirements 
if you change the volume serial number or do a partial restore that does not 
modify the VTOC. If you do a restore and change the VTOC size without 
changing the volume serial number, the volume must be varied offline after it is 
restored. You should not do a restore on a volume with an indexed VTOC. 


Copying a Volume. There are no operational requirements if you change the 
volume serial number or do not modify the VTOC of the receiving volume. If 
you do a copy and change the VTOC size without changing the volume serial 
number, the volume must be varied offline after it is copied. You should not 
do a copy from a volume with an indexed VTOC. 


Operations on Volumes Containing an Indexed VTOC 


You should use Device Support Facilities to convert a VTOC to a nonindexed 
format to update the volume. If you do not, take note of the following 
information: 


Initializing a Volume. If you do not change the volume serial number, the 
volume should be varied offline before starting the job. 


Restoring a Volume from a Dump Tape. There are no operational requirements 
if you change the volume serial number or do a partial restore that does not 
modify the VTOC or VTOC index. If you do a restore and modify the VTOC 
or VTOC index without changing the volume serial number, the volume should 
be varied offline after it is restored. 
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=, e Copying a Volume. There are no operational requirements if you change the 
( volume serial number of the receiving volume or do a partial dump without 
modifying the VTOC or VTOC index. If you modify the VTOC or VTOC 
index without changing the volume serial number, the receiving volume should 
be varied offline after it is copied. 


e Shared DASD Considerations. In shared DASD environments, whenever the 
VTOC index is modified or relocated or whenever the volume is changed from 
indexed VITOC to OS VTOC or from OS VTOC to indexed VTOC, the device 
should be varied offline to the sharing system or systems. 


Accessing the VTOC with DADSM Macros 


You may use DADSM or CVAF to access the VTOC and its index. (CVAF access 
is described in “‘Accessing the WTOC and its Index with CVAF Macros”’ on 
page 42.) DADSM macros and associated tasks include: 


| LSPACE - Obtain free space, volume fragmentation, and VTOC 
| status information for a DASD volume. 
OBTAIN - Read a DSCB from a VTOC. 
PARTREL - Release unused space from a SAM or PAM data set. 
REALLOC - DASD space allocation. 
RENAME - Rename a non-VSAM data set. 
SCRATCH - Release all space and DSCBs for a non-VSAM data set. 


( > The PARTREL macro is described in “Releasing Unused Space from a DASD 
; Data Set’? on page 169. The REALLOC macro is described in *‘Allocating a 
DASD Data Set” on page 174. 


This section tells how to use the LSPACE, OBTAIN, SCRATCH, and RENAME 
macro instructions. These macros are most commonly used by the operating 
system and the data set utility programs (IEHMOVE, IEBCOPY, and 
IEHPROGM), but you may use them in your own routines. The functions you can 
perform with these macros are: 


| LSPACE Obtaining free space, volume fragmentation, and VTOC status 
| information for a DASD volume 


OBTAIN Reading a data set control block from the VTOC 
RENAME Changing the name of a data set 
SCRATCH _ Deleting a data set 


You can obtain free space, volume fragmentation, and VTOC status information 
for a DASD volume by using the LSPACE macro instruction. LSPACE returns 
information to any of three user-specified areas. 


You can read a data set control block (DSCB) into virtual storage by using the 
OBTAIN and CAMLST macro instructions. There are two ways to specify the 
DSCB that you want to read: by using the name of the data set associated with the 
DSCB, or by using the absolute track address of the DSCB. You must provide a 
140-byte data area in virtual storage, into which the DSCB is to be read. When 
you specify the name of the data set, an identifier (format-1 or format-4) DSCB is 
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read into virtual storage. To read a DSCB other than a format-1 or a format-4 
DSCB, you must specify an absolute track address (see ““Example”’ on page 32). 


You can change a data set name by using the RENAME and CAMLST macro 
instructions. This causes replacement of the data set name in the data set’s 
format-1 DSCB with the new name. 


You can delete a non- VSAM data set by using the SCRATCH and CAMLST 
macro instructions. This causes deletion of the data set’s DSCBs. 


Coding examples, programming notes, and exception return code descriptions 
accompany the following macro instruction descriptions. 


Note: You cannot use LSPACE, OBTAIN, SCRATCH, or RENAME macro 
instructions with either a SYSIN or SYSOUT data set. 


Obtaining DASD Volume Information (LSPACE) 


You can use the LSPACE macro to obtain free space, volume fragmentation, and 
VTOC status information for a DASD volume. LSPACE normally returns status 
information (such as LSPACE subfunction, return code, and reason code) to the 
parameter list. The format of the LSPACE parameter list is shown in Figure 8 on 
page 24. You may request that LSPACE return additional information such as the 
total number of free extents on the volume, or the fragmentation index. This 
additional information can be returned in either: 


e A message return area: ‘“Message Return Area” on page 27 describes the 
format and content of the message return area. 


e A data return area: “Data Return Area” on page 27 describes the format and 
content of the data return area. 


e A Format-4 DSCB return area: “Format 4 DSCB Return Area” on page 28 
describes the format and content of the Format-4 DSCB return area. 


The format of the LSPACE macro is: 


[symbol] | LSPACE [UCB= {addr | (reg)}] 
[,.MSG= {addr | (reg) | 0} 
| DATA={adadr | (reg) | 03] 
[| .SMF={TEST | YES | NONE}] 


[,F4DSCB= {addr | (reg) | 03] 
| L| (L,MSG) | (L,DATA) 
| (E,addr) | (E,(reg))}] 





UCB = {addr | (rez)} | 
specifies the address of the UCB for the volume whose free space 
information you are requesting. 


addr—RX-type address £~ 
specifies the address of a fullword that contains the address of the " y 
UCB. ~~ 
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(reg)—(2-12) 


specifies a register containing the UCB address for the device. 


When using the standard (MF=I) form of the macro, you must provide a 
UCB address. 


MSG =$addr | (reg) | 0} | DATA={adadr | (reg) | 03 
specifies the way LSPACE is to return free space information. 


Note: The MSG and DATA parameters are mutually exclusive. 


MSG = {addr | (reg) | 03 
specifies the address of a caller-provided 30-byte message return area 
into which LSPACE returns either a free space message or, for 
unsuccessful requests, status information. For a description of this 
area, see ‘Message Return Area” on page 27. 


addr—RX-type address 
specifies the address of the message return area. 


(reg}—(2-12) 
specifies a register containing the address of the message return 
area. 


specifies that you do not want the free space message. This is 
the default for all forms of the macro except execute. 


DATA= fadar | (reg) | 03 
specifies the address of a caller-provided 36-byte data return area into 
which LSPACE returns free space and volume information. For a 
description of this area, see ‘‘Data Return Area”’ on page 27. 


addr—R.X-type address 
specifies the address of the data return area. 


(reg)—(2-12) 
specifies a register containing the address of the data return 
area. 

0 


specifies that you do not want the free space and volume 
information. 


SMF={TEST | YES | NONE} 
specifies the type of SMF processing desired. 


TEST 
specifies that LSPACE is to test for an SMF system and whether SMF 
volume information is desired. Only programs executing in supervisor 
state, protect key 0-7, or APF-authorized may specify this operand. 
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YES 
specifies that you want LSPACE to provide SMF volume information. & 
Only programs executing in supervisor state, protect key 0-7, or Mi ou 
APF-authorized may specify this operand. 


NONE 
specifies that you do not want LSPACE to provide SMF volume 
information. This is the default for all forms of the macro except 
execute. 


F4DSCB= $adadr | (reg) | 03 
specifies the address of a 96-byte DSCB return area provided by the calling 
program, into which LSPACE returns the volume’s format-4 DSCB. Fora 
description of the format-4 DSCB fields, see the DSCB4 data area section in 
Debugging Handbook. 


addr—RX-type address 
specifies the address of the format-4 DSCB return area. 


(reg) —(2-12) 
specifies a register containing the address of the format-4 DSCB 
return area. 

0 


specifies that you do not want the data portion of the format-4 DSCB 
for the volume. This is the default for all forms of the macro except 


execute. 
MF={I| D | (D,MSG) | (D,DATA) | L| (L,MSG) | (L,DATA) | (E,addr) | (E,(reg))} —_ 
specifies the form of the LSPACE macro. 
I 
specifies the inline (standard) form of the macro. This generates an 
inline parameter list containing the required variables, loads the 
address of the parameter list in register 1, and issues an SVC 78. This 
form is the default. 
D 
generates a DSECT that maps the LSPACE parameter list. See 
Figure 8 on page 24 for the format of the LSPACE parameter list. 
(D,MSG) 
generates a DSECT that maps the message return area. For the 
format of the area, see “‘Message Return Area” on page 27. 
(D,DATA) 
generates a DSECT that maps the data return area. For the format of 
the area, see “Data Return Area” on page 27. 
L 


generates the required constants in the calling program. You may then 
issue the execute form of the macro, which uses these constants. 


MVS/XA System—Data Administration 





(L,MSG) 
generates the required message return area constants in the calling 
program. 


(L,DATA) 
generates the required data return area constants in the calling 
program. 


(E,addr) 
loads the address of the parameter list specified by addr into register 1, 


puts the specified variables into the parameter list, and issues an SVC 
78. 


(E,(reg)) 
loads the address of the parameter list specified by (reg) into register 1, 
puts the specified variables into the parameter list, and issues an SVC 
78. 
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Name 


LSPAPL 
LSPAPLID 
LSPANGTH 
LSPAFLAG 
LSPASMFY 
LSPASMFT 
LSPADATA 
LSPARSVB 
LSPARSVD 
LSPAERCD 
LSPASFID 
LSPASFPC 
LSPASFVP 
LSPASFUS 
LSPASFNQ 
LSPASF45 
LSPASFNS5 
LSPASFRV 
LSPASF4X 
LSPASFEX 
LSPASFFO 
LSPASFVR 
LSPASFVD 
LSPASFRT 
LSPASFRS 
LSPARSO1 
LSPARSO2 
LSPARSO3 
LSPARS04 
LSPARSOS5 
LSPARS06 
LSPARSO7 
LSPARSO8 
LSPARSO9 
LSPAUCB 
LSPAFRSP 
LSPAFMT4 


Offset 


00(X'00') 
04(X'04") 
06(X'06') 


07(X'07') 
08(X'08"') 
09(X'09') 


10(X'0A") 
11(X'0B') 


12(X'0C') 
16(X'10') 
20(X'14') 


Bytes 


X'80! 
X'40! 
X'20! 


ooeK XXXX 


X'00' 
X'01' 
X'02' 
X'03' 
X'04' 
X'05! 
X'06' 
X'80' 
X'81' 
X'82' 
X'83' 
X'84! 


X'O1' 
X'02! 
X'03! 
X'04! 
X'05! 
X'06! 
X'Q7' 
X'08! 
X'09! 
4 

4 

4 


Description 


EBCDIC 'LSPA' 

Length of parameter list 
Parameter flag byte 

SMF= YES 

SMF=TEST 

Free space data request 

Reserved 

Reserved 

LSPACE return code 

LSPACE subfunction 

Processing complete 

Validate parameters 

Check UCB status 

Enq on SYSZDMNT 

Read F4 and first F5 (EXCP) 
Read next F5 (EXCP) 

Read volume label (EXCP) 

Read F4 and maps (CVAFDIR) 
Get free extents (CVAFDSM) 
Get FO count (CVAFDSM) 

Get VIR count (CVAFDSM) 
Check for VRF (CVAFVRF) 
Subfunction return code 
Subfunction reason code 

Check parameter list storage key 
Check parameter list ID 

Check LSPACE flag 

Check authorization for SMF flag 
Check message or data return area storage key 
Check format-4 DSCB return area storage key 
Check UCB address 

Check for virtual UCB address 
Check for zero VTOC pointer 
UCB address 

Address of message or data return area 
Address of format-4 DSCB 


Figure 8. Format of the LSPACE Parameter List (MF=D) 


Note: For more information about the LSPAERCD, LSPASFID, LSPASFRT, and 
LSPASFRS fields, see “LSPACE Status Information” on page 26. 
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| Return Codes from LSPACE 





| Return codes from LSPACE are as follows: 


| Code Meaning 

| 0(X'00') Successful processing 

| 4(X'04') Permanent I/O Error 

| 8(X'08') Non-Standard OS Volume 

| 12(X'0C') Invalid Parameter or UCB Not Ready 


| 16(X'10') Invalid Parameter List 
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LSPACE Status Information 


Register 0 and the LSPACE macro’s parameter list? contain additional diagnostic 
information. Figure 9 shows the relationship between the following LSPACE 
parameter list fields: 


LSPAERCD (return code) 
LSPASFID (subfunction identifier) 


LSPASFRT (subfunction return code) 
LSPASFRS (subfunction reason code) 


LSPAERCD 


| 

| 

| 

| 

| 

| LSPASFID LSPASFRT LSPASFRS Description 

| 16 (X'10') 01 (X'01') N/A 01 (X'01"') Bad parm list storage key 

| 16 (X'10') 01 (X'01') N/A 02 (X'02') Bad parm list ID 

| 12 (X'0C') 01 (X'01') N/A 03 (X'03') Invalid LSPACE flag 

| 12 (X'0C') 01 (X'01') N/A 04 (X'04') Not authorized for SMF 

| 12 (X'0C') 01 (X'01') N/A 05 (X'05') Bad MSG/DATA area storage key 
| 12 (X'0C') 01 (X'0O1') N/A 06 (X'06') Bad FMT4 area storage key 

| 12 (X'0C') 01 (X'01') N/A 07 (X'07') UCB not found 

| 12 (X'0C') 01 (X'01') N/A 08 (X'08') UCB not direct access device 
| 12 (X'0C') 01 (X'01"') N/A 09 (X'09') UCB VTOC pointer is zero 

| 12 (X'0C') 02 (X'02') N/A N/A Invalid UCB status 

| 12 (X'0C') 03 (X'03') ENO RETC N/A Failed ENQ on SYSZDMNT 
| 08 (X'08') 04 (X'04') N/A N/A F5s are invalid 

| 04 (X'04') 04 (X'04') ECB STAT N/A Error reading F4 and first FS 
| 04 (X'04') 05 (X'05') ECB STAT N/A Error reading next F5 

[| 04 (X'04') 06 (X'06') ECB STAT N/A Error reading volume label 

| 04 (X'04') 80 (X'80') DIR RETC CVSTAT Error getting F4/space maps a 
| 04 (X'04') 81 (X'81') DSM RETC CVSTAT Error getting free extents 

| 04 (X'04') 82 (X'82') DSM RETC CVSTAT Error getting FO count 

| 04 (X'04') 83 (X'83') DSM RETC CVSTAT Error getting VIR count 

| 04 (X'04') 84 (X'84') VRF RETC CVSTAT Error checking for VRF 

| 00 (X'00') 00 (X'00') N/A N/A No problems 


Figure 9. LSPACE Status Information Relationships 


LSPACE Subfunction Return Code and Reason Code 


| The following table identifies the information returned in the LSPASFRT and 
| LSPASFRS fields of the LSPACE macro’s parameter list. 


N/A - Not Applicable 

CVSTAT - CVSTAT field of CVAF parameter list 
ENQ RETC - Return code from ENQ 

DIR RETC - Return code from CVAFDIR 

DSM RETC - Return code from CVAFDSM 

VRF RETC - Return code from CVAFVRF 

ECB STAT - ECB completion code 





| 2 Status information does not appear in the parameter list for return code 16. 
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| LSPACE Information Return Areas 


| The LSPACE macro returns status information to the parameter list and, 
| optionally, the return of volume information to any of the three caller requested 
| return areas described below.3 


| Message Return Area: LSPACE returns information to a 30-byte message return 
| area (Figure 10). If you provide a message return area with the MSG option, 

| LSPACE returns EBCDIC text, qualified by return codes as shown in Figure 11. 
| 


| LSPMSG DSECT Message Area 
| LSPMTEXT DS CL30 Message Text 


| Figure 10. DADSM LSPACE Free Space Information Format, MF=(D,MSG) 


Return Text or 
Code Explanation 
16(X'10') No text returned (invalid parameter list or SMF indicator) 
12(X'0C') Text: LSPACE—UCB NOT READY 

Text: LSPACE—UCBVTOC IS ZERO 

Text: LSPACE—INVALID PARAMETER 

Text: LSPACE—NOT A DIRECT ACCESS VOL 
O8(X'08') Text: LSPACE—NON-STANDARD OS VOLUME 
04(X'04') Text: LSPACE—PERMANENT I/O ERROR 
00(X'00') Text: SPACE=aaaa,bbbb,cccc/dddd,eeee 


where: 

aaaa = Total number of free cylinders 

bbbb = Total number of additional free tracks 

cccc = Total number of free extents 

dddd = Number of cylinders in largest free extent 

eeee = Number of additional tracks in largest free extent 


| Figure 11. DADSM LSPACE Message Area Contents 


| Data Return Area: If you provide a data return area with the DATA option, 
| LSPACE returns information as described in Figure 12. 


| 3 Requests for the MSG and DATA areas are mutually exclusive. LSPACE checks to 
| ensure that the storage key of each information return area is equal to the caller’s key 
| or that the caller is authorized prior to its use. 
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Name Offset Bytes Description 

LSPDRETN 00(X'00') 1 Return area status byte 

LSPDSPAC X'80' Returned space information 

LSPDFOCN X'40! Returned format-0 DSCB count 
LSPDVRCN X'20! Returned free VIR count 

LSPDRRES 1X XXXX Reserved 

LSPDSTAT 01(X'01') 1 Status byte 

LSPDIXDS X'80! Index exists for VTOC 

LSPDIXAC X'40! Index VTOC active 

LSPDIRES XX XXXX Reserved 

LSPDRSV1 02(X'02') 2 Reserved 

LSPDNEXT 04(XK'04') 4 Number of free extents 

LSPDTCYL 08(X'08') 4 Total free cylinders 

LSPDTTRK 12(X'0C') 4 Total additional free tracks 

LSPDLCYL 16(X'10') 4 Number of cylinders in largest free extent 
LSPDLTRK 20(X'14') 4 Number of additional tracks in largest free extent 
LSPDFOS 24(X'18') 4 Format-0 DSCB count 

LSPDVIRS 28(X'1C') 4 Free VIR count 

LSPDFRAG 32(X'20') 4 Fragmentation index! 


Figure 12. Format of the LSPACE Data Return Area 

Note to Figure 12: 

1 The fragmentation index is a numeric representation of the relative size and 
distribution of free space on the volume. A large index value indicates a high 
degree of fragmentation. 

Format 4 DSCB Return Area: \f you provide a format-4 DSCB return area with the 

F4DSCB option, LSPACE returns information as described by the DSCB4 data 

area in Debugging Handbook. 
Example of LSPACE Using Message Return Area 


The following example requests that LSPACE return free space information in the 
message return area. 


LSPAMFIM LSPACE MSG=MYMSG, UCB=(R10) ,MF=I 


Example of LSPACE Using Data Return Area 


The following example requests that LSPACE return free space information in the 
data return area. 


LSPAMFID LSPACE DATA=MYDATA,UCB=(R10) ,MF=I 
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| Example of LSPACE Specifying List and Execute Forms 


The following example uses the list form of the macro to define the parameter list, 
and the execute form to refer to the same parameter list 


LSPALIST LSPACE MSG=MYDATA,MF=L 


LSPAEX LSPACE MF=(E,LSPALIST) ,UCB=(R10) 


Reading a Control Block from the VTOC 


Reading a DSCB by Name (OBTAIN and CAMLST SEARCH) 





If you specify a data set name using OBTAIN and the CAMLST SEARCH option, 
the OBTAIN routine reads the 96-byte data portion of the identifier (format-1) 
DSCB and the absolute track address of the DSCB into virtual storage. The 
absolute track address is a 5-byte field in the form CCHHR. The absolute track 
address field contains zeros for VSAM and VIO data sets. 


Because the VTOC does not contain a format-1 DSCB for a suballocated VSAM 
data space, an OBTAIN request, which searches the VTOC for such a data space’s 
DSCB, fails. If the volume contains VSAM data sets, the OBTAIN routine uses 
information from the VSAM catalog to build a pseudo format-1 DSCB, setting its 
CCHHR to zeros. 


The format is: 


[symbol] OBTAIN | listname-addrx 
listname CAMLST | SEARCH 


sasname-relexp 
,vol-relexp 
»wkarea-relexp 





listname-addrx 
points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 


SEARCH 
this operand must be coded as shown. 


dsname-relexp 
specifies the virtual storage location of a fully qualified data set name. The 


area that contains the name must be 44 bytes long. 


Note: A DSNAME of 44 bytes of X'04' (X'040404...04') can be used to 
read a format-4 DSCB. 
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vol-relexp | 
specifies the virtual storage location of the 6-byte volume serial number on ( | 
which the DSCB is located. 4 


wkarea-relexp 
specifies the virtual storage location of a 140-byte work area that you must 
define. 


Example: In the following example, the identifier (format-1) DSCB for data set 
A.B.C is read into virtual storage using the SEARCH option. The serial number of 
the volume containing the DSCB is 770655. 


OBTAIN DSCBABC READ DSCB FOR DATA 
* SET A.B.C INTO DATA 
* AREA NAMED WORKAREA 
DSCBABC CAMLST SEARCH , DSABC, VOLNUM,WORKAREA 
DSABC DC CL44'A.B.C' DATA SET NAME 
VOLNUM DC CL6'770655' VOLUME SERIAL NUMBER 
WORKAREA DS 140C 140-BYTE WORK AREA 


Note: Check the return codes. 


The OBTAIN macro instruction points to the CAMLST macro instruction. 
SEARCH, the first operand of CAMLST, specifies that a DSCB be read into 
virtual storage, using the data set name you have supplied at the address indicated 
in the second operand. DSABC, the second operand, specifies the virtual storage 
location of a 44-byte area into which you have placed the fully qualified name of 
the data set whose format-1 DSCB is to be read. VOLNUM, the third operand, 
specifies the virtual storage location of a 6-byte area into which you have placed 
the serial number of the volume containing the required DSCB. WORKAREA, the 
fourth operand, specifies the virtual storage location of a 140-byte work area into 
which the DSCB is to be returned. 


Control is returned to your program at the next executable instruction following the 
OBTAIN macro instruction. If the DSCB has been successfully read into your 
work area, register 15 contains zeros. Otherwise, register 15 contains one of the 
following return codes. The return codes are shown in decimal, with hexadecimal 
values in parentheses. 
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Return Codes from OBTAIN (Reading by data set name) 


Code Meaning 
4(X'04') The required volume was not mounted. 


8(X'08') The format-1 DSCB was not found in the VTOC of the 
specified volume. 


12(X'0C') <A permanent I/O error was encountered, or an invalid 
format-1 DSCB was found when processing the specified 
volume, or an unexpected error return code was received 
from CVAF (Common VTOC Access Facility). 


16(X'10') Invalid work area pointer. 


After execution of these macro instructions, the first 96 bytes of the work area 
contain the data portion of the identifier (format-1 or format-4) DSCB; the next 5 
bytes contain the absolute track address (CCHHR) of the DSCB. These 5 bytes 
contain zeros for VSAM or VIO data sets. 


Reading a DSCB by Absolute Device Address (OBTAIN and CAMLST SEEK) 


{ You can read any DSCB from a VTOC using OBTAIN and the CAMLST SEEK 
option. You specify the SEEK option by coding SEEK as the first operand of the 
CAMLST macro and by providing the absolute device address of the DSCB you 
want to read, unless the DSCB is for a VIO data set. Only the SEARCH option 
can be used to read the DSCB of a VIO data set. 


The format is: 


[symbol] listname-addrx 
listname SEEK 


scchhr-relexp 
,vol-relexp 
»wkarea-relexp 





listname-addrx 
points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 


SEEK 
this operand must be coded as shown. 


cchhr-relexp 
specifies the virtual storage location of the 5-byte absolute device address 
(CCHHR) of a DSCB. 
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vol-relexp 7 
specifies the virtual storage location of the 6-byte volume serial number on 
which the DSCB is located. 


wkarea-relexp | 
specifies the virtual storage location of a 140-byte work area that you must 
define. 


Example: In the following example, the DSCB at actual-device address 

X'00 00 00 O01 O7' is returned in the virtual storage location READAREA, 
using the SEEK option. The DSCB resides on the volume with the volume serial 
number 108745. 


OBTAIN ACTADDR READ DSCB FROM 
* LOCATION SHOWN IN CCHHR 
* INTO STORAGE AT LOCATION 
* NAMED READAREA 
ACTADDR CAMLST SEEK ,CCHHR, VOLSER, READAREA 
CCHHR DC XL5'0000000107' ABSOLUTE TRACK ADDRESS 
VOLSER DC CL6'108745' VOLUME SERIAL NUMBER 
READAREA DS 140C 140-BYTE WORK AREA 


Note: Check the return codes. 


The OBTAIN macro points to the CAMLST macro. SEEK, the first operand of 
CAMLST, specifies that a DSCB be read into virtual storage. CCHHR, the second 
operand, specifies the storage location that contains the 5-byte actual-device 
address of the DSCB. VOLSER, the third operand, specifies the storage location 
that contains the serial number of the volume where the DSCB resides. The fourth 
operand, READAREA, specifies the storage location to which the 140-byte DSCB 
is to be returned. 


Control is returned to your program at the next executable instruction following the 
OBTAIN macro instruction. If the DSCB has been successfully read into your 
work area, register 15 contains zeros. Otherwise, register 15 contains one of the 
following return codes. The return codes are shown in decimal, with hexadecimal 
values in parentheses. 
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Return Codes from OBTAIN (Reading by Absolute Device Address) 





Code Meaning 
4(X'04') The required volume was not mounted. 


8(X'08') The format-1 DSCB was not found in the VTOC of the 
specified volume. 


12(X'OC') <A permanent I/O error was encountered or an 
unexpected error return code was received from CVAF. 


16(X'10"') Invalid work area pointer. 


20(X'14') The SEEK option was specified and the absolute track 
address (CCHHR) is not within the boundaries of the VTOC. 


Deleting a Data Set from the VTOC (SCRATCH and CAMLST SCRATCH) 


You can use the SCRATCH and CAMLST macro instructions to delete a 
non- VSAM data set. SCRATCH processing deletes the associated data set control 
( ; blocks (DSCBs) and makes the space occupied by the data set available for 
: reallocation. Be aware that this process may not erase the data from the disk. 
Data sets that contain sensitive data should be erased (overwritten with zeros) 
before their space is made available. This erase can either be done before issuing 
the SCRATCH macro, or be requested in scratch processing by 


e Providing an associated RACF ERASE attribute, or 
e Activating bit 21 (X'00 00 04 00') of the SCRATCH parameter list. 


Authorized callers of SCRATCH may set bit 22 to '1' to override the RACF 
profile ERASE attribute. 


If you want to scratch a data set being processed using virtual input/output (VIO), 
the data set must have been allocated for use by your job. Scratching VIO data 
sets not allocated to your job is not allowed. 


If the data set to be deleted is sharing one or more cylinders with one or more data 
sets (a split-cylinder data set), the space will not be made available for reallocation 
until all data sets on the shared cylinders are deleted. 


A data set cannot be deleted if the expiration date in the identifier (format-1) 
DSCB has not passed, unless you choose to ignore the expiration date. You may 
specify that DADSM is to ignore the expiration date by specifying the OVRD 
option in the CAMLST macro instruction. 


££ | DADSM SCRATCH processing supports three never-scratch dates. To ensure that 
\ § | | a data set will never be scratched, specify the expiration date as either of the 
- | following: | 
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e 1999.365 
e 1999.366 
e 1999.999 


For information on RACF-defined data sets, see RACF General Information 
Manual. You may scratch a RACF-defined data set (that is, the DSCB indicates 
RACF-defined) only if you have alter access authority to either the data 
set/volume serial in the DATASET class, or to the volume serial in the DASDVOL 
class (if the volume is RACF-defined). 


If a data set to be deleted is stored on more than one volume, either a device must 
be available for mounting the volumes or at least one volume must be mounted. In 
addition, all other required volumes must be serially mountable. 


When deleting a data set, you must build a volume list in virtual storage. This 
volume list consists of an entry for each volume on which the data set resides. The 
first two bytes of the list indicate the number of entries in the list. Each 12-byte 
entry consists of a 4-byte device code, a 6-byte volume serial number, and a 2-byte 
scratch status code that should be initialized to zero. 


If the space to be deleted is a VSAM data space, you must use the DELETE 
command provided by access method services. For complete information about the 
DELETE command, see Access Method Services Reference. 


Volumes are processed in the order that they appear in the volume list. The 
volume at the beginning. of the list is processed first. If a volume is not mounted, a 
message is issued to the operator requesting that a volume be mounted. (A volume 
mount message will not be issued for a mass storage system (MSS) virtual volume; 
however, a status code will be returned to your program.) This is only done if 
register 0 has been loaded with the address of the UCB associated with the device 
where unmounted volumes are to be mounted. (The device must be allocated to 
your job.) If you do not load register 0 with a UCB address, its contents must be 
zero, and at least one of the volumes in the volume list must be mounted before the 
SCRATCH macro instruction is issued. 


If the requested volume cannot be mounted, the operator issues a reply indicating 
that the request cannot be fulfilled. A status code is then set in the last byte of the 
volume pointer (the second byte of the scratch status code) for the unavailable 
volume, and the next volume indicated in the volume list is processed. 


The format is: 


[symbol] listname-addrx 
listname SCRATCH 


ydsname-relexp 
vol list-relexp 


[,OVRD] 





listname-addrx 
points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 
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SCRATCH 
this operand must be coded as shown. 


dsname-relexp 
specifies the virtual storage location of a fully qualified data set name. The 
area that contains the name must be 44 bytes long. The name must be 
defined by a C-type Define Constant (DC) instruction. 


vol list-relexp 
specifies the virtual storage location of an area that contains a volume list. 
The area must begin on a halfword boundary. 


OVRD 
when coded as shown, specifies that the expiration date in the DSCB should 
be ignored. | 


Example: In the following example, data set A.B.C is deleted from two volumes. 
The expiration date in the identifier (format-1) DSCB is ignored. 


SR 0,0 SET REG O TO ZERO 
SCRATCH DELABC DELETE DATA SET A.B.C 
* FROM TWO VOLUMES, 
* IGNORING EXPIRATION 
= DATE IN THE DSCB 
DELABC CAMLST SCRATCH ,DSABC, , VOLIST, , OVRD 
DSABC DC CL44'A.B.C' DATA SET NAME 
VOLIST DC H'2' NUMBER OF VOLUMES 
DC X'3030200E' 3380 DISK DEVICE CODE 
DC CL6'000017' VOLUME SERIAL NO. 
DC Heo? SCRATCH STATUS CODE 
DC X'3030200E' 3380 DISK DEVICE CODE 
DC CL6'000018' VOLUME SERIAL NO. 
DC H'OQ' SCRATCH STATUS CODE 


Note: Check the return codes and SCRATCH status codes. 


The SCRATCH macro instruction points to the CAMLST macro instruction. 
SCRATCH, the first operand of CAMLST, specifies that a data set be deleted. 
DSABC, the second operand, specifies the virtual storage location of a 44-byte 
area where you have placed the fully qualified name of the data set to be deleted. 
VOLIST, the fourth operand, specifies the virtual storage location of the volume 
list you have built. OVRD, the sixth operand, specifies that the expiration date in 
the DSCB of the data set to be deleted be ignored. 


When you attempt to delete a password-protected data set that is not also 
RACF-protected, the operating system issues a message (IEC301A) to ask the 
operator at the console or the terminal operator of a remote console to enter the 
password. The data set will be scratched only if the password supplied is 
associated with a WRITE protection mode indicator. The protection mode 
indicator is described in Chapter 5, ''Password Protecting Data Sets." 


Control is returned to your program at the next executable instruction following the 


SCRATCH macro instruction. If the data set has been successfully deleted, 
register 15 will contain zeros, and the scratch status code in the volume list entry 
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for each volume will be set to zero. Otherwise, register 15 will contain one of the 

return codes that follow. To determine whether the data set has been successfully 
deleted from each volume on which it resides, you must examine the scratch status 
code, that is, the last byte of each entry in the volume list. 


Return Codes from SCRATCH 


Code Meaning 


4(X'04') No volumes containing any part of the data set were mounted, nor 
did register 0 contain the address of a unit that was available for 
mounting a volume of the data set. The data set may be a VIO data 
set that was not allocated during your job. (This return code is 
accompanied by a scratch status code of 5 in each entry of the 
volume list.) 


8(X'08') An unusual condition was encountered on one or more volumes. 
12(X'0C') The volume list passed was invalid. The scratch status code (the last 


byte of each volume list entry) will not have been modified during 
scratch processing. 
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Status Codes from SCRATCH 


After the SCRATCH macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates one of the following conditions in binary codes: 


Scratch 

Status 

Code Meaning 

0 All DSCBs for the data set have been deleted from the 
VTOC on the volume pointed to. 

1 The VTOC of this volume does not contain the format-1 
DSCB for the data set to be deleted. 

2 The macro instruction failed when the correct password 
was not supplied in the two attempts allowed, or an 
attempt was made to scratch a VSAM data space or data set 
cataloged in an Integrated Catalog Facility catalog. 

3 The data set was not deleted from this volume because 
either the OVRD option was not specified or the 
retention cycle has not expired. 

4 A permanent I/O error was encountered, or an invalid 
format-1 DSCB was found when processing this volume, 
or an unexpected error return code was received from 
CVAF. 

5 It could not be verified that this volume was mounted, 
and no device was available for mounting this volume. 

6 The operator was unable to mount this volume. 

For IBM Mass Storage Systems (MSS), a volume mount 
failure occurred. 

For a JES3-managed virtual volume, JES3 would not 
allow the volume to be mounted. 

7 The specified data set could not be scratched 
because it was being used. 

8 The DSCB indicates the data set is defined to RACF, 


but either the user is not authorized to access the 

data set or the volume, or the data set is a VSAM 

data space, or the data set is cataloged in an Integrated Catalog 
Facility catalog, or the data set is not defined to RACF. 
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Renaming a Data Set in the VTOC (RENAME and CAMLST RENAME) 


You rename a data set that is not cataloged in an Integrated Catalog Facility 
catalog or VSAM catalog by using the RENAME and CAMLST macro 
instructions. These cause the data set name in all format-1 DSCBs for the data set 
to be replaced by the new name you supply. (VIO data sets cannot be renamed.) 


If a data set to be renamed is stored on more than one volume, either a device must 
be available for mounting the volumes, or at least one volume must be mounted. In 
addition, all other volumes of the data set must be serially mountable. 


For information on RACF-defined data sets, see RACF General Information 
Manual. Only a user with alter access authority may rename a RACF-defined data 
set. 


When renaming a data set, you must build a volume list in virtual storage. This 
volume list consists of an entry for each volume on which the data set resides. The 
first two bytes of the list indicate the number of entries in the list. Each 12-byte 
volume list entry consists of a 4-byte device code, a 6-byte volume serial number, 
and a 2-byte rename status code that should be initialized to zero. Volumes are 
processed in the order in which they appear in the volume list. The first volume on 
the list is processed first. If a volume is not mounted, a message is issued to the 
operator requesting that the volume be mounted. (A volume mount message will 
not be issued for an MSS volume; however, a status code is returned to your 
program.) This is only done if you indicate the direct access device on which 
unmounted volumes are to be mounted by loading register 0 with the address of the 
UCB associated with the device to be used. (The device must be allocated to your 
job.) If you do not load register 0 with a UCB address, its contents must be zero, 
and at least one of the volumes in the volume list must be mounted before the 
RENAME macro instruction is executed. 


If the operator cannot mount a volume in the volume list, a reply is issued that the 
request cannot be fulfilled. A status code is then set in the last byte of the volume 
list entry (the second byte of the rename status code) for the unavailable volume, 
and the next volume indicated in the volume list is processed or requested. 


The format is: 


[symbol] RENAME | listname-addrx 
listname CAMLST | RENAME 


ydsname-relexp 
new name-relexp 
»vol list-relexp 





listname-addrx 


points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 


RENAME 
this operand must be coded as shown. 


38 MVS/XA System—Data Administration 











dsname-relexp 
specifies the virtual storage location of a fully qualified data set name to be 
replaced. The area that contains the name must be 44 bytes long. The name 
must be defined by a C-type Define Constant (DC) instruction. 


new name-relexp 
specifies the virtual storage location of a fully qualified data set name that is 
to be used as the new name. The area that contains the name must be 44 
bytes long. The name must be defined by a C-type Define Constant (DC) 
instruction. 


vol list-relexp 
specifies the virtual storage location of an area that contains a volume list. 
The area must begin on a halfword boundary. 


Example: In the following example, data set A.B.C is renamed D.E.F. The data 
set resides on two volumes. 


SR 0,0 SET REG O TO ZERO 
RENAME DSABC CHANGE DATA SET 
NAME A.B.C TO D.E.F 


DSABC CAMLST  RENAME,OLDNAME,NEWNAME, VOLIST 


OLDNAME DC CL44'A.B.C' OLD DATA SET NAME 
NEWNAME DC CL44'D.E.F' NEW DATA SET NAME 
VOLIST DC H'2' TWO VOLUMES 

DC X'3030200E' 3380 DISK DEVICE CODE 

DC CL6'000017' VOLUME SERIAL NO. 

DC H'O' RENAME STATUS CODE 

DC X'3030200E' 3380 DISK DEVICE CODE 

DC CL6'000018' VOLUME SERIAL NO. 

DC H'O' RENAME STATUS CODE 


Note: Check the return codes and RENAME status codes. 


The RENAME macro instruction points to the CAMLST macro instruction. 
RENAME, the first operand of CAMLST, specifies that a data set be renamed. 
OLDNAME, the second operand, specifies the virtual storage location of a 44-byte 
area where you have placed the fully qualified name of the data set to be renamed. 
NEWNAME, the third operand, specifies the virtual storage location of a 44-byte 
area where you have placed the new name of the data set. VOLIST, the fourth 
operand, specifies the virtual storage location of the volume list you have built. 


Control is returned to your program at the next executable instruction following the 
RENAME macro instruction. If the data set has been successfully renamed, 
register 15 will contain zeros, and the rename status code in the volume list entry 
for each volume will be set to zero. Otherwise, register 15 will contain one of the 
return codes below. To determine whether the data set has been successfully 
renamed on each volume where it resides, you must examine the rename status 
code, the last byte of each entry in the volume list. 
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Return Codes from RENAME 


Code 


4(X'04') 


8(X'08') 


12(X'0C') 








Meaning 


No volumes containing any part of the data set were 
mounted, nor did register 0 contain the address of a unit 
that was available for mounting a volume of the data set 

to be renamed. 

The data set may be a VIO data set and cannot be renamed. 
(This return code is accompanied by a rename status code 
of 5 in each entry of the volume list.) 


An unusual condition was encountered on one or more 
volumes. 


The volume list passed was invalid. 

The rename status code, the last byte of each volume list 
entry, will not have been modified during rename 
processing. 


After the RENAME macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates one of the following conditions in binary code: 
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Rename 
Status 
Code Meaning 


0 The format-1 DSCB for the data set has been renamed in 
the VTOC on the volume pointed to. 


1 The VTOC of this volume does not contain the format-1 
DSCB for the data set to be renamed. 


2 The macro instruction failed when the correct password 
was not supplied in the two attempts allowed, or the 
user tried to rename a VSAM data space or VSAM data 
set cataloged in an Integrated Catalog Facility catalog. 


3 A data set with the new name already exists on this 
volume. 


4 A permanent I/O error was encountered, or an invalid 
format-1 DSCB was found when trying to rename the data 
set on this volume, or an unexpected error return code 
was received from CVAF. 


5 It could not be verified that the volume was mounted, 
and no device was available for mounting the volume. 


6 The operator was unable to mount this volume. 
For Mass Storage Systems (MSS), a volume mount 
failure occurred. 
For a JES3-managed virtual volume, JES3 would not 
allow the volume to be mounted. 


7 The specified data set could not be renamed on 
this volume because it was being used. 


8 The data set is defined to RACF, but either the 
user is not authorized to alter the data set 
or the data set is defined to RACF on multiple 
volumes. 


When you attempt to rename a password-protected data set, the operating system 
issues a message (IEC301A) to ask the operator or remote console operator to 
verify the password. The data set will be renamed only if the password supplied is 
associated with a WRITE protection mode indicator. The protection mode 
indicator is described in Chapter 4, “‘Password Protecting Data Sets” on 

page 111. 
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Accessing the VTOC and its Index with CVAF Macros 


Serialization and Updating 


Identifying the Volume 


You may use CVAF or DADSM to access the VTOC or its index. DADSM access 
is described in ‘Accessing the VWTOC with DADSM Macros” on page 19. 


CVAF macros and associated tasks include: 


CVAFDIR - Directly access DSCBs or VTOC index records. 
CVAFDSM - Obtain volume free space information. 
CVAFFILT - Read sets of DSCBs for one or more DASD data sets. 


CVAFSEQ - Retrieval of the following: 
- Data set names from an active VTOC index. 
- DSCBs in physical-sequential order. 
- DSCBsS in data set name order (index required). 


CVAFTST 


Appendix A, “(CVAF VTOC Access Macros” on page 231, contains detailed 
descriptions of these macros. Appendix B, “Examples of VTOC Access Macros’’ 
on page 259, contains examples of their use. 


CVAF requires that you provide all necessary system resource serialization for 
your request. You can only ensure the integrity of multiple data elements (sets of 
DSCBs and/or VIRs) returned by CVAF if you serialize system resources 
adequately. You compound this exposure if you must make multiple CVAFFILT 
requests for a desired set of DSCBs and/or VIRs. 


You must weigh possible system performance loss because of serialization against 
the potential loss of data integrity. If you make updates without adequate 
serialization, you may compromise the integrity of the volume’s VTOC, the VTOC 
index, and/or any associated data set. 


CVAF only honors requests to modify the volume’s VTOC and/or index from 
authorized programs. 


CVAF assumes that an authorized program holds an exclusive RESERVE (or 
ENQ) on the qname (major name) of SYSVTOC, rname (minor name) of the 
volume’s serial number, with the scope of SYSTEMS. The SYSVTOC qname does 
not serialize access to the format-1 DSCB for a data set. You may provide this 
serialization by allocating the data set with disposition OLD, MOD, or NEW (not 
SHR). This causes the proper ENQ, ensuring that no other job can update that 
data set’s format-1 DSCB. 


If you are authorized, you may identify the volume to the CVAFDIR, CVAFDSM, 
CVAFFILT, and CVAFSEQ macros by specifying the address of its UCB. If you 
are not authorized, you must identify the volume by specifying the address of a 
SAM or EXCP DEB opened to the volume’s VTOC. 


The DEB can be obtained by opening a DCB using the RDJFCB and OPEN 
TYPE=J macros. The DCBs DDNAME is that of a DD statement allocated to the 
unit whose VTOC is to be accessed. After issuing the RDJFCB macro, the 
JFCBDSNM field is overlaid with the data set name of the format-4 DSCB: 
44X'04'. You open the DCB for INPUT by using OPEN TYPE=J. The DEB 
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Determine if a DASD volume has an active VTOC index. 





Using Registers 


address is in DCB field DCBDEBA. The OPEN macro is described under 
“OPEN—lInitialize Data Control Block for Processing the JFCB”’ on page 148; 
the RDJFCB macro is described under ‘“RDJFCB—Read a Job File Control 
Block” on page 137. 


If a CVAF macro call specifies IOAREA=KEEP, a subsequent CVAF call using a 
different CVPL may omit the UCB and DEB keywords and supply the IOAREA 
address from the other CVPL. You can use the IOAREA keyword to do this. 


The requirements cited above do not apply to the CVAFTST macro. The 
CVAFTST macro only allows you to identify the VTOC by specifying a UCB, and 
does not require that you be authorized. 





Register 1 contains the address of the CVAF parameter list (CVPL). Register 15 
contains the return code when processing for a function is complete. 





Generating a CVPL (CVAF Parameter List) 


All the CVAF macros except CVAFTST use the CVPL to pass parameters to 
CVAF. The CVAFTST macro expands to provide its only parameter (UCB 
address) in register 1, and calls the associated CVAF module. CVAF uses the 
CVPL to return information related to the CVAF request. 


CVAF generates a CVPL when you specify the CVAFDIR, CVAFDSM, 
CVAFFILT, or CVAFSEQ macro with MF=L or MF=I as a subparameter. If 
you do not specify the MF subparameter, MF=I is the default. Upon return, the 
CVI1IVT bit indicates whether an indexed or nonindexed VTOC was accessed. 
The CVSTAT field contains feedback when an error occurs. The address of the 
map records buffer list is returned in the CVMRCDS field. The address of the 
VIER buffer list is returned in the CVIRCDS field. CVAF returns the CVAF I/O 
area address in the CVIOAR field. CVAF returns the CVAF Filter Save Area 
address in the CVFSA field. 


You may use the CVPL generated by the MF=L or MF=I form of the CVAFDIR, 
CVAFDSM, CVAFFILT, or CVAFSEQ macros (by using the MF=E keyword) to 
execute a different function than that specified by the macro that originally 
generated the CVPL. If you specify a CVAF filter request, you must use a CVPL 
generated by the CVAFFILT macro. (To support the CVFSA field, the 
CVAFFILT macro generates a CVPL four bytes larger than that generated by the 
other CVAF macros. ) 


The ICVAFPL macro maps the CVPL. The format of the CVPL is shown in 
Figure 13 on page 44. 
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Name 


CVPL 
CVLBL 
CVLTH 


CVFCTN 
CVSTAT 
CVFL1 
CV1IIVT 
CV1IOAR 
CV1PGM 


CV1IMRCDS 


CV1IRCDS 
CV1MAPIX 


CV1IMAPVT 
CV1IMAPVL 


CVFL2 
CV2HIVIE 
CV2VRF 
CV2CNT 
CV2RCVR 
CV2SRCH 
CV2DSNLY 
CV2VER 
CV2NLEVL 
CVFL3 
CV3FILT 
CV3IXERR 


CVUCB 
CVDSN 
CVFCL 
CVBUFL 
CVIRCDS 
CVMRCDS 
CVIOAR 
CVDEB 
CVARG 
CVSPACE 
CVEXTS 
CVBUFL2 
CVVRFDA 
CVCTAR 
CVFSA 


Figure 13. Format of the CVAF Parameter List (CVPL) 


Offset 


00(X'00') 
04(X'04') 


06(X'06') 
07(X'07') 
08(X'08') 


09(X'09') 


10(X'0A') 


11(X'0B') 
12(X'0C') 
16(X'10') 
16(X'10') 
20(X'14') 
24(X'18') 
28(X'1C') 
32(X'20') 
36(X'24') 
40(X'28') 
44(X'2C') 
48(X'30') 
52(X'34') 
56(X'38') 
60(X'3C') 
64(X'40') 


Bytes 


~-XX XXXX 


A HPhA HPA HAHA AAA HAH HE 





Description 


EBCDIC 'CVPL' 

Length of CVPL 

64(X'40') for macros other than CVAFFILT 
68(X'44') for CVAFFILT macro 
Function byte (See Figure 14 on page 45) 
Status information 

First flag byte 

Indexed VTOC accessed 
IOAREA=KEEP 
BRANCH=(YES,PGM) 
MAPRCDS= YES 
IXRCDS=KEEP 
MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

Second flag byte 

HIVIER= YES 

VRF data exists 

COUNT= YES 
RECOVER= YES 

SEARCH= YES 
DSNONLY= YES 

VERIFY= YES 

New highest level VIER (output) 
Third flag byte 
FLTAREA=KEEP 

Index error found 

Reserved 

Reserved 

UCB address 

Data set name address 

Filter criteria list address 

Buffer list address 

Index VIRs buffer list address 
Map VIRs buffer list address 
I/O area address 

DEB address 

Argument address 

SPACE parameter list address 
Extent table address 

New VRE VIXM btffer list address 
VRF data address 

Count area address 

Filter save area 


Note: The CVAFFILT macro generates a CVPL four bytes longer (total length = 
X'44') than that generated by the other CVAF macros (total length = X'40'). 
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Buffer Lists 


The possible contents of the CVFCTN field in the CVPL and their meanings are as 


follows: 

Name Description 

CVDIRD X'01' -CVAFDIR ACCESS=READ 
CVDIWR X'02' -CVAFDIR  ACCESS=WRITE 
CVDIRLS X'03' -CVAFDIR ACCESS=RLSE 
CVSEQGT X'04' -CVAFSEQ ACCESS=GT 
CVSEQGTE X'05' -CVAFSEQ ACCESS=GTEQ 
CVDMIXA X'06' -CVAFDSM ACCESS=IXADD 
CVDMIXD X'07' -CVAFDSM ACCESS=IXDLT 
CVDMALC X'08' -CVAFDSM ACCESS=ALLOC 
CVDMRLS X'09' -CVAFDSM ACCESS=RLSE 
CVDMMAP = X'0OA' -CVAFDSM ACCESS=MAPDATA 
CVVOL X'OB' -CVAFVOL ACCESS=VIBBLD 
CVVRFRD X'OC' -CVAFVRF ACCESS=READ 
CVVRFWR X'OD' -CVAFVRF ACCESS=WRITE 
CVFIRD X'OE' -CVAFFILT ACCESS=READ 
CVFIRES X'OF' -CVAFFILT ACCESS=RESUME 
CVFIRLS X'10' -CVAFFILT ACCESS=RLSE 


Figure 14. CVFCTN Field of CVPL—Contents and Definitions 


A buffer list consists of one or more chained control blocks, each with a header and 
buffer list entries, obtained and initialized by your program before calling CVAF. 
The header indicates whether the buffer list is for DSCBs or VTOC index records. 
The entries point to and describe the buffers. 


You can create buffer lists in two ways: 


e Directly, when you fill in the arguments and buffer addresses of DSCBs or 
VIRs to be read or written 


¢ Indirectly (by CVAF), when you code the IXRCDS=KEEP and/or 
MAPRCDS= YES keywords 


The ICVAFBFL macro maps CVAF buffer lists. Figure 15 on page 46 shows the 
format of a buffer list header. Figure 16 on page 47 shows the format of a buffer 
list entry. 


Buffer List Header: The buffer list header indicates whether the buffer list 
describes buffers for DSCBs or for VTOC index records. The DSCB bit must be 
set to one and the VIR bit to zero for CVAF to process a request to read or write a 
DSCB. CVAF requires that you provide buffer lists and buffers in your program’s 
protect key. CVAF uses the protect key and subpool fields in the buffer list header 
only if you code ACCESS=RLSE. 
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Name 


BFLHDR 
BFLHNOE 
BFLHFL 
BFLHKEY 
BFLHVIR 
BFLHDSCB 


BFLHSP 
BFLHFCHN 


Figure 15. 











Each buffer list header contains a count of the number of entries in the buffer list 
that directly follows the header. 


The forward chain address chains buffer lists together. You must not chain DSCB 
buffer lists to VIR buffer lists, or VIR buffer lists to DSCB buffer lists. 


The format of the buffer list header is shown in Figure 15. 


Offset 


0(X'00') 
0(X'00') 
1(X'01") 


2(X'02') 
3(X'03') 
4(X'04') 


Format of a Buffer List Header 


Bytes Description 

8 Buffer list header 

1 Number of entries 

1 Flag byte and key 

XXXX .. Protect key of buffer list and buffers 
X!'08! Buffer list entries describe VIRs 

X'04! Buffer list entries describe DSCBs 

eta: XX Reserved 

1 Reserved 

i Identifies the subpool of buffer list and buffers 
4 Forward chain address of next buffer list 


Buffer List Entry: A buffer list contains one or more entries. Each entry provides 
the buffer address, the length of the DSCB or VIR buffer, the argument, and an 
indication whether the argument is an RBA, a TTR, or a CCHHR. 


The fields and bit uses are listed below. 


For a VIR buffer, the TTR and CCHHR bits must be 0, and the RBA bit must 


be 1. 


For a DSCB buffer, the RBA bit must be 0, and one of either the TTR or 


CCHHR bits must be set to 1 (they must not both be 1). 


The BFLEAUPD bit is an output indicator from CVAF that the BFLEARG 


field of a VIR buffer list was updated. 


The BFLEMOD bit indicates that a VIR buffer was modified and must be 
written; if no BFLEMOD bits are on in any of the entries fora CVAFDIR 


ACCESS=WRITE, all buffers are written. 


The BFLESKIP bit is used to cause an entry to be ignored. 


The BFLEIOER bit is an output indicator from CVAF to indicate an I/O error 


occurred during reading or writing of the DSCB or VIR. 


The BFLELTH field is the length of the buffer; for a DSCB buffer, the length 
must be 96 or 140; for a VIR buffer, the length must be the length of the 


buffer divided by 256. 


The BFLEARG field is the argument of the DSCB or VIR. Specify the desired 
format of the 5-byte field by setting either the BFLECHR, BFLETTR, or 
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Name 


BFLE 
BFLEFL 
BFLERBA 
BFLECHR 
BFLETTR 
BFLEAUPD 
BFLEMOD 
BFLESKIP 
BFLEIOER 


BFLELTH 


BFLEARG 
BFLEATTR 
BFLEARBA 
BFLEBUF 


BFLERBA bit to 1. The respective BFLEARG values and formats are as 
follows: 


CCHHR=5 byte CCHHR 


TTR=O0TTRO 


RBA=One byte of 0 followed by a 4-byte RBA 


The optional and required values for BFLEARG are dependent upon the variables 
associated with a given request. These are described in the following 
request-oriented topics. 


The format of the buffer list entry is shown in Figure 16. 


Offset 


0(X'00') 
0(X'00') 


1(X'01') 
2(X'02') 


3(X'03') 
4(X'04"') 
4(X'04') 
8(X'08') 


Bytes 


Figure 16. Format of a Buffer List Entry 


Accessing the DSCB Directly 


Description 


Buffer list entry 

Flag byte 

Argument is RBA 

Argument is CCHHR 

Argument is TTR 

CVAF updated argument field 
Data in buffer has been modified 
Skip this entry 

I/O error 

Reserved 

Reserved 

Length of VIR buffer divided by 256, or length of DSCB 
buffer 

Argument of VIR or DSCB 

TTR of DSCB 

RBA of VIR 

Buffer address 


You may use the CVAFDIR macro to read or write a DSCB. You may also use it 
to read or write VTOC index records for indexed VTOCs. “CVAFDIR Macro” on 
page 231 discusses detailed information about the CVAFDIR VTOC access 


macro. 


After a CVAFDIR call, you may test the CVAF parameter list bit, CVIIVT, to 
determine whether the VTOC is indexed or nonindexed. 
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Specifying a Data Set Name to Read or Write a DSCB: If you want to read or write _ 
a single DSCB by specifying only the data set name (that is, BFLEARG is zero) ff 
you must specify either ACCESS=READ or ACCESS= WRITE. ew 


Specify the address of the data set name in the DSN keyword. Specify the address 
of the buffer list in the BUFLIST keyword. Each of these areas and the associated 
buffers must be in your program’s protect key. 


The buffer list must contain at least one buffer list entry with the skip bit off and a 
pointer to a 96-byte buffer. You must not provide 140-byte buffers. You may 
chain buffer lists together, but CVAF only uses the first eligible entry. 


For an indexed VTOC, CVAF searches the index for the data set name and, if it is 
found, puts the DSCB argument into the buffer list entry and uses it to read or 
write the DSCB. If CVAF cannot find the data set name in the index, CVAF does 
a key search of the VTOC. : 


For a nonindexed VTOC, CVAF uses a channel program to do a key search of the 
VTOC to locate the data set name and read or write the DSCBs. If CVAF finds 
the data set name, CVAF puts the DSCB argument into the buffer list entry. 


The DSCB argument returned in the buffer list entry is in the format determined by | 
the buffer list entry bits BFLECHR or BFLETTR. 


If CVAF does not find the data set name in the VTOC, it provides a return code of 
'4' in register 15, and an error code of '1' in the CVSTAT field. 


Specifying the DSCB Location: Yf you want to read or write a DSCB by specifying 
the DSCB’s location (that is, BFLEARG), you must specify either 
ACCESS=READ or ACCESS=WRITE. 


Specify the address of the data set name in the DSN keyword. Specify the address 
of the buffer list in the BUFLIST keyword. Each of these areas and the associated 
buffer(s) must be in your program’s protect key. 


The buffer list must have at least one buffer list entry with the skip bit off and a 
pointer to a 96-byte or 140-byte buffer. You may chain buffer lists together, but 
CVAF only uses the first eligible entry. 


If the buffer is for a 96-byte read or write, CVAF issues a channel program to 
verify that the key in the DSCB is the same as the 44-byte data set name you | 
provide. CVAF does not execute the read or write unless the keys match. If they 
do not match, CVAF ignores the specified BFLEARG and reads or writes the 
DSCB according to the rules given in “‘Specifying a Data Set Name to Read or 
Write a DSCB” on page 48. 


If the buffer is for a 140-byte read or write, CVAF issues a channel program to 
read or write the DSCB at the location specified in the buffer list entry. CVAF 
does not use the data set name you specified. If you specify VERIFY=YES, 
CVAF verifies that the designated DSCB is a format-0 DSCB before issuing the 
write channel program. 





nara 
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Reading or Writing VTOC Index Records: You may read or write VIRs explicitly by 
using the BUFLIST keyword. You may read them implicitly by using the IXRCDS 
and MAPRCDS keywords. You may supply a buffer list address in the BUFLIST 
keyword to read or write one or more VIRS. The buffer list header must have the 
VIR bit set to one and the DSCB bit set to zero. CVAF inspects each entry in the 
buffer list (and any chained extensions). If the skip bit is set to zero, the RBA bit 
is set to one (and the CCHHR and TTR bits are set to zero), and the buffer 
address is nonzero, CVAF processes the entry. CVAF uses the RBA in the 
argument field of the buffer list entry to read or write a VIR using the buffer 
address. CVAF processes read and write requests in the order of their appearance 
in the buffer list. 


Each of the storage areas you provide must be in your program’s protect key. 


For a write request, CVAF inspects the modification bit in the buffer list entries. If 
the bit is not set to '1' in any entry, CVAF writes all the entries. CVAF sets the 
modification bit to zero for entries whose VIR is written. 


If you specify the keywords MAPRCDS= YES and/or IXRCDS=KEEP and, at 
the same time, you do not provide an address in the CVMRCDS/CVIRCDS fields 
of the CVPL, CVAF reads the map records and the first high-level VTOC index 
entry record. 


Reading Map Records and VIERS: lf you want to read the VTOC index map 
records and first high-level VIER, and retain them in virtual storage, you must code 
either ACCESS=READ or ACCESS=WRITE. CVAF does not require either the 
DSN or BUFLIST fields. 


If you want to read and retain map records, you must code MAPRCDS=YES. The 
CVAF parameter list field CVMRCDS must be zero. CVAF obtains a buffer list 
with the number of entries and buffers required to read all the map VIRs. CVAF 
puts the buffer list address into the CVMRCDS field. 


If you want to read and retain the first high-level VIER and (if this requires an 
index search) all VIERs read, you must code IXRCDS=KEEP. If the CVAF 
parameter list field CVIRCDS is zero, CVAF obtains a buffer list with entries and 
buffers, and reads the first high-level VIER. CVAF determines the number of 
entries and buffers. If CVIRCDS is not zero, CVAF reads only the VIERs 
required for an index search. 


You can only ensure the integrity of the maps and VIER that CVAF reads if you 
enqueue the VITOC and (for shared DASD) issue a reserve to the unit. 


You must release the map and VIER buffers acquired and retained by CVAF by 
issuing a subsequent CVAF call. 


Releasing Buffers and Buffer Lists Obtained by CVAF: You may release buffers and 
buffer lists acquired by CVAF in the three following ways: 


e To free the MAP records buffer list, code MAPRCDS=NO or 
MAPRCDS=(NO, addr) specifying any ACCESS. 


e To free the index records buffer list, code IXRCDS=NOKEEP or 
IXRCDS=(NOKEEP, addr) specifying any ACCESS. 
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e Issue a CVAF call with ACCESS=RLSE, and specify a buffer list address with 
the BUFLIST keyword. 


CVAF frees all eligible buffers and any buffer lists if they become empty. Eligible 
buffers are those pointed to by buffer list entries with the skip bit off. CVAF frees 
a buffer list if none of its buffer list entries have the skip bit on. If buffer lists are 
chained together, CVAF checks and frees all buffer lists if appropriate. 


Ensure that you do not request CVAF to release the same buffer list twice by 
specifying its address in more than one place. 


Accessing DSNs or DSCBs in Sequential Order 
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Each CVAFSEQ call may request the return of one of the following: 
e One format-1 or format-4 DSCB in indexed (data-set-name) order. 


e One or more DSCBs in physical-sequential order (if you are unauthorized, you 
can only request one DSCB). 


e The next data set name in the index. 


CVAF reads the DSCBs into buffers supplied with the BUFLIST keyword. 
“CVAFSEQ Macro” on page 251 discusses detailed information about the 
CVAFSEQ VTOC access macro. 


Use the buffer list to specify the argument of each DSCB to be read. For indexed 
access, you must request 96-byte DSCBs in the buffer list. For physical-sequential 
access, you must request 140-byte DSCBs. 


If you select indexed order, CVAF returns each format-1 or format-4 DSCB whose 
name is in the index. If you want CVAF to return only the data set names in the 
index (not the DSCBs), specify DSJNONLY=YES. In this case, CVAF returns the 
CCHHR of the DSCB in the argument area supplied through the ARG keyword. 
CVAF updates the DSN area you specify, with the data set name of each DSCB 
read, each time you issue CVAFSEQ. 


Initiating Indexed Access (DSN Order): To initiate indexed access (DSN order), 
either supply in the area coded through the DSN keyword 44 bytes of binary zeros 
(to indicate the first data set name in the index) or supply the data set name you 
want to serve as the starting place for the index search. 


The name that CVAF returns in the DSN area is the one equal to or greater than 
the DSN supplied, depending on the specification of the ACCESS keyword. 
CVAF updates the DSN field. 


The ACCESS keyword determines whether the search is for a DSN greater than or 
equal to that which you specify. 


If you specify DSNONLY=NO, CVAF returns the DSCB and argument to you, 
using the buffer list you provide with the BUFLIST keyword. CVAF uses the first 
entry in the buffer list with the skip bit set to '0' and a nonzero buffer address. 
You must specify the argument value if you set either the TTR or CCHHR bit in 
the buffer list entry to '1'. The default is CCHHR. For indexed access, the DSCB 
size in the buffer list entry must be 96 bytes. 
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If you specify DSNONLY=YES, you must specify the CCHHR argument in the 
ARG area. 


Note that the data set name of the format-4 DSCB is in the index and that CVAF 
may return its name (44 bytes of X'04'). The format-4 DSCB’s name is likely to 
be the first data set name in the VTOC index. 


Initiating Physical-Sequential Access: To initiate physical-sequential access, you 
must either specify DSN=0, or not specify the DSN parameter at all. To begin the 
read, you must initialize the argument field in the first buffer list entry to zero or to 
the argument of the DSCB. If the argument is zero, CVAF uses the argument of 
the start of the VTOC. 


You must set the DSCB size to 140 in buffer list entries. 


The ACCESS= specification determines whether CVAF reads the DSCB whose 
argument is supplied or the DSCB following it. 


For example, to read the first DSCB (the format-4 DSCB) in the VTOC, you may 
set the BFLEARG in the first buffer list entry to zero and specify 
ACCESS=GTEQ in the CVAFSEQ macro. If you subsequently specify 
ACCESS=GT, CVAF reads the second DSCB (the first format-5 DSCB). 


If you are authorized, CVAF reads as many DSCBs as there are entries in the 
buffer list, with a single CVAF call. If you are not authorized, CVAF only reads 
one DSCB. 


CVAF only uses one buffer list. CVAF does not inspect a second buffer list 
chained from the first. If you are authorized, CVAF uses all entries in the buffer 
list. CVAF does not inspect the skip bit. Each entry must have a buffer address, 
the length field set to 140, and the TTR or CCHHR bit set to 1 (if neither bit is 
set, CVAF sets the CCHHR bit on). If you are unauthorized, CVAF only uses the 
first entry. CVAF updates the argument field of each buffer list entry with the 
argument of the DSCB. The argument value is returned in either TTR or CCHHR 
format, depending on whether you set the TTR or CCHHR bit to 1 in the buffer 
list entry. The default is CCHHR. 


CVAF uses only the argument in the first entry to begin the search. CVAF does 
not inspect arguments in subsequent entries. If you specify a nonzero argument 
value in the first entry, a DSCB with that argument must exist. 


CVAF indicates an end-of-data condition by providing return code 4 in register 15, 
and a value of X'20' in the CVSTAT field. CVAF sets the argument fields of all 
buffer list entries following the last DSCB read, to zero (the first entry is zero if 
CVAF does not read any DSCBs). 


Note that CVAF reads all DSCBs, including format-O0 DSCBs. You cannot be 
certain that you have read all format-1 through format-6 DSCBs until CVAF had 
read the entire VIOC. For a nonindexed VTOC, the format-4 DSCB field 
DS4HPCHR contains the CCHHR of the last format-1 DSCB. Format-2 through 
format-6 DSCBs may reside beyond that location. For an indexed VTOC, the 
VMDS contains information about which DSCBs are format-0 DSCBs. 
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Reading Sets of DSCBs with CVAF Filter 


The CVAF filter service retrieves sets of DSCBs into buffers provided by the 
calling program. The following text summarizes this service and its requirements. 


e You may invoke the CVAF filter service by issuing the CVAFFILT macro. 
““CVAFFILT Macro” on page 245 describes the macro’s syntax and 
parameters. 


e You request DSCBs by specifying either one or more fully qualified data set 
names, or one partially qualified name. See “Filter Criteria List” on page 53 
and “‘Examples of Partially Qualified Names for CVAFFILT” on page 250 for 
further information. 


e For each of the qualifying data sets, CVAF Filter returns DSCBs in the order 
that they are chained in the VTOC: format 1, format 2, then format 3. CVAF 
does not return DSCBs of other formats. 


e CVAF filter service returns complete DSCB chains for one or more qualifying 
data sets into caller-provided buffers. See ‘““Example of CVAFFILT Macro 
Sequences” on page 57 and ‘‘Example 3: Using the CVAFFILT Macro” on 
page 271 for further information. CVAF filter service does not return a 
partial DSCB chain: 


— If you do not provide enough buffers to hold all of the requested DSCBs, 
CVAF filter service returns one or more complete DSCB chains and/or a 
status code (CVSTAT in the CVPL). The status code indicates whether 
or not you may use a “RESUME” CVAF call to retrieve the rest (or more) 
of the requested DSCBs. See ‘RESUME Capability” for specific 
information. 


— If the total number of buffers provided is not sufficient to contain a data 
set’s complete DSCB chain, CVAF filter service sets a status byte 
(FCLDSNST in the FCL), ignores the data set, and processes the next 
qualifying data set. You can avoid this situation by providing a minimum 
of eleven DSCB buffers (enough for a data set at the 123 extent limit). 


e You must identify a single DASD volume in the CVAF parameter list (CVPL). 
CVAF filter service supports both indexed and nonindexed VTOCs. 


e When calling CVAF, your program can be in either 24-bit or 31-bit addressing 
mode. If it is in 31-bit mode, the control blocks shown in Figure 17 on 
page 53 may reside above the 16Mb line. All these areas must be accessible in 
your program’s storage key. 


RESUME Capability: If CVAF filter service terminates before returning a data 
set’s DSCBs because you did not provide enough buffers, CVAF filter service 
saves the information necessary for a RESUME function in the filter save area 
(You must specify FLTAREA=KEEFP on the initial CVAFFILT call to cause 
CVAF filter service to obtain and keep the filter save area). 


To allow RESUME processing to execute correctly, you must maintain the 
relationship between the requested volume (identified by CVDEB, CVUCB, or a 
kept IOAREA), your FCL, and CVAF’s FSA. If you observe this requirement, 
you can initiate and resume multiple CVAF filter service operations 
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asynchronously on one or more DASD volumes. You can ensure this relationship 
by providing a unique CVPL and FCL for the duration of the 
READ/RESUME/RELEASE sequence associated with each logical request. 


If you issue an ACCESS=RESUME without having previously specified 
FLTAREA=KEEP, CVAF filter service provides return code '4' in register 15 
and '66' in the CVSTAT field. 


If you specify FLTAREA=KEEP, you must issue a subsequent CVAFFILT call 
with the ACCESS=RLSE keyword to release the filter save area storage. 


DSN 
Buffer 
DSN 
DSCB 
Buffer 
DSN 


Buffer 


Figure 17. Control Blocks Required for CVAF Filter Services 


Filter Criteria List 


The filter criteria list consists of two kinds of elements; a list header, and a variable 
number of list entries. The list entries immediately follow the header, and each 
entry represents a different data set name to be processed by CVAF filter. The 
header and entries, shown in Figure 18 and Figure 19 are mapped by the 
ICVFCL macro. The format of the FCL header is shown in Figure 18. 
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Name 


FCLID 
FCLCOUNT 
FCLDSCBR 
FCLIFLAG 
FCLI1LIST 
FCLIORDR 


FCL2FLAG 


FCL2SEQ 
FCL2SDIR 


FCLDRSV 


Offset 
00(X'00') 
04(X'04') 


06(X'06') 
08(X'08') 


09(X'09') 


10(X'0A") 


Bytes Description 

4 EBCDIC 'FCL '! 

2 Number of data set name entries provided in the list. 

2 Number of DSCBs returned 

1 Request flag byte 

X'80! List contains fully qualified data set names 

X'40! FCL data set name order requested 

XX XXXX Reserved 

1 Status flag byte 

X'80' CVAFFILT executed sequential VTOC access 

X'40! CVAFFILT executed sequential VTOC access, but did at least 
one direct DSCB read 

XX XXXX Reserved 

6 Reserved 


Figure 18. Format of a Filter Criteria List (FCL) Header 


FCLID 
Must be a 4-character EBCDIC constant of 'FCL '. 


FCLCOUNT 
Specifies the number of data set name entries (FCLDSN) supplied in the list. 
You must not change this parameter between the initial CVAFFILT cail and 
any subsequent RESUME operations. 


e When you specify a partially-qualified data set name, you must specify 
FCLCOUNT = 1. See “Examples of Partially Qualified Names for 
CVAFFILT”’ on page 250 for the format of partially qualified data set 
names. 


e When you specify a list of fully qualified names, CVAFFILT processes 
only the number of names specified in FCLCOUNT. 


FCLDSCBR 
Indicates the total number of DSCB entries (including format-1, format-2, 
and format-3) returned to the caller’s buffers by a single CVAFFILT call. 


Because CVAF may encounter an error after successfully processing a data 
set, you may: 


1. Initialize FCLDSCBR to 0 before each READ and RESUME call. 


2. Upon return from CVAF filter service, process the number of DSCBs 
indicated by FCLDSCBR,. 


3. Then, interpret the CVAF return code and CVSTAT. 


FCLIFLAG 
Define your request for ACCESS=READ with this flag byte. Any 
subsequent RESUME requests refer to a copy of these bits in the filter save 
area (FSA). 
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FCLILIST 
Set this bit to 1 if you specify a list of fully qualified data set names. 
Set it to O if you specify a single partially qualified data set name. 


FCLIORDR 
If you specify that CVAF return DSCB chains in the data set name 
sequence implied by the placement of the FCLDSN elements, set this 
bit to 1. Note that: 


e If you allow CVAF to determine the sequence of return for 
format-1 DSCBs, you may realize a performance gain. 


e CVAF always returns DSCBs for a given data set in format-1, 
format-2, format-3 order. 


e If you specify a single partially-qualified data set name, CVAF 
filter does not use this field. 


FCL2FLAG 
CVAF filter indicates the following status conditions in this byte. 


FCL2SEQ 
CVAF filter sets this bit to 1 if it determines that its sequential VTOC 
access path is most efficient. If CVAF filter selects the direct VTOC 
access path, it sets this field to 0. 


FCL2SDIR 
CVAF filter sets this bit to 1 if storage limitations within its sequential 
VTOC access path require direct DSCB reads. CVAF initializes this 
bit to 0 on each ACCESS=READ and ACCESS=RESUME request. 
You may test this bit when CVAF filter returns control to you, to 
determine if you must take some action to relieve the storage 
limitation. 
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Name 


FCLDSN 
FCLDSNST 


FCLDSNLG 
FCL3FLAG 
FCL3UPDT 


FCLDSNRV 
FCLDSNA 


Offset 


16(X'10') 
00(X'00') 


01(X'01') 
02(X'02') 


03(X'03') 
04(X'04') 


The format of the FCL entry is shown in Figure 19. 


Bytes 


8 

1 

X'00! 
X'01' 
X'02! 
X'03! 
X'04' 
X'05! 


X'80! 


* 
/ 


Description | hed 


Data set name information entry 

Data set name status 

Data set name not yet processed 

DSCBs returned successfully 

Data set name not found 

Error in DSCB chain. RESUME function recommended. 
Error in CVAFFILT processing. RESUME not recommended. 
Insufficient user buffer list elements. RESUME function 
recommended. 

Data set name length 

Flag byte 

This data set name processed during this invocation 


XXX XXXX Reserved 


Reserved 
Data set name address 


Figure 19. Format of a Filter Criteria List (FCL) Entry 


FCLDSN 


Contains data set name information. This, and the following fields are 
repeated in the FCL as a “‘set,’”’ as many times as indicated by the value in 
FCLCOUNT. 


FCLDSNST 
Indicates DSCB retrieval status. 


e CVAF filter initializes this byte to 0 for ACCESS=READ 
requests. 


¢ CVAF filter updates this byte after processing this data set name 
for either ACCESS=READ or ACCESS=RESUME. 


e« ACCESS=RESUME requests do not process data set names 
whose FCLDSNST field is non-zero, thus results may be 
unpredictable if you alter this field. 


¢ For partially-qualified data set name requests, CVAF filter does 
not post the FCLDSNST field until it has returned all DSCB 
chains for all qualifying data sets. CVAF filter posts the highest 
numeric value which applied during the its processing. 


e For fully-qualified data set name requests, CVAF filter returns a 
FCLDSNST byte for each data set name. If the value is greater 
than 1, CVAF filter has not returned any DSCBs for the 
associated data set name. 


See Figure 19 for the meanings of the possible values in this field. 


foe 
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FCLDSNLG 
Indicates length of data set name. You must provide this value. 


FCL3FLAG 


This is the.status flag byte associated with the data set name pointed 
to by FCLDSNA. 


FCL3UPDT 
This bit indicates that CVAF filter processed the associated 
data set name during the current invocation of CVAFFILT. 


e When initializing for either a READ or RESUME request, 
CVAF filter sets this bit to 0. 


e When CVAF filter has completed processing for the 
associated data set name, it sets this bit to 1. 


FCL3DSNRV 
Reserved, unused. 


FCLDSNA 
Specifies the address of a fully-qualified data set name, or, if this is the 
only data set name and FCLILIST is 0, a partially-qualified data set 
name. You must provide both this address and the storage area to 
which it points. 


Example of CVAFFILT Macro Sequences: The following example demonstrates the 
order in which you might issue CVAFFILT macro calls to: 


1. Request the DSCBs for a list of data sets. 


2. Resume CVAFFILT processing interrupted because of insufficient user 
buffers. 


3. Release the kept filter save area. 
The example assumes the following conditions: 


e You are an authorized caller (that is, you are specifying a UCB address and 
IOAREA=KEEP). 


e You have initialized a CVAF buffer list as follows: 
— You have specified four buffers. 


— You have defined the buffer list address in your program with the label 
"BUFADDR'. 


— You will use the same buffer list for ACCESS=READ and 
ACCESS=RESUME processing. 


e You have initialized a filter criteria list (FCL) as follows: 


— FCLCOUNT = 6 (You are requesting DSCB chains for six data set 
names. ) 
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— FCLILIST = '1'B (The data set names are fully qualified.) 


ff ™. 
— FCLIORDR = '1'B (You want the DSCB chains returned in the order a 
implied by data set name elements in the FCL.) ~ 
— You have initialized each of the six data set name elements such that they 
form a list requesting SYS1.A, SYS2.B, SYS3.C, SYS4.D, SYS5.E, and 
SYS6.F respectively. 
e The first five data sets have DSCB chain lengths or 1, 5, 2, 3, and 1 
respectively on the volume. 
e The sixth data set (SYS6.F) is not defined on the volume. 
To obtain an initialized CVPL, you could issue the following CVAFFILT macro 
(list form—does not call CVAF). This example requests the branch entry to 
CVAF and specifies that the caller is in supervisor state. 
CVPLIST CVAFFILT BRANCH=(YES,SUP) ,MF=L 
To obtain the first set of DSCB chains, you could issue the following CVAFFILT 
macro (execute form—calls CVAF). This example specifies that the filter save 
area is to be kept to allow for ACCESS=RESUME calls. The IOAREA is to be 
kept for improved efficiency. 
CVAFFILT ACCESS=READ, BUFLIST=bufaddr,FCL=fcladdr, 
UCB=ucbaddr , FLTAREA=KEEP , IOAREA=KEEP, 
MF=(E,CVPLIST) . 
eS, 
This CVAFFILT call would return DSCBs as follows: oe 
Buffer Contents of Buffer 
1 Format-1 DSCB, SYS1.A 
2 Format-1 DSCB, SYS3.C 
3 Format-3 DSCB, SYS3.C 
4 Undefined (unused) 


CVAF filter would provide return code = 4, CVSTAT = X'40' (RESUME 
recommended), and FCLDSCBR = 3 (CVAF would return a total of three 
DSCBs for the two data sets). CVAF would not return DSCBs for data set 
SYS2.B because its chain contains more DSCBs than the total number of buffers 
provided. To retrieve SYS2.B’s DSCBs, you would have to specify at least five 
buffers AND execute another ACCESS=READ. (Even though CVAF allows you 
to specify a different buffer list for each READ OR RESUME, or modify the 
existing list between READ and RESUME calls, modifying the FCL would result 
in unpredictable results.) Buffer entry 4 would not have any DSCBs returned, 
because SYS4.D’s DSCB chain size is larger than the number of remaining buffers. 
The FCL status information would be as follows: 


DSN FCLDSNST FCL3UPDT Comments 

SYS1.A 1 1 DSCBs returned from this call 
SYS2.B 5 1 DSCB chain exceeds total buffers 
SYS3.C 1 1 DSCBs returned from this call 
SYS4.D O O DSCBs may be returned by RESUME 
SYS5.E 0 O DSCBs may be returned by RESUME 
SYS6.F 0 0 DSCBs may be returned by RESUME 
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Because this CVAFFILT invocation recommends RESUME, and you specified 
a FLTAREA=KEEP, you could use the following execute form of CVAFFILT to 
( obtain more DSCB chains: 


CVAFFILT ACCESS=RESUME,MF=(E,CVPLIST) 


This CVAFFILT call would return DSCBs as follows: 


Buffer Contents of Buffer 


1 Format-1 DSCB, SYS4.D 
2 Format-2 DSCB, SYS4.D 
3 Format-3 DSCB, SYS4.D 
4 Format-1 DSCB, SYS5.E 


CVAF filter would provide return code = 0, CVSTAT = 0 (request completed), 
and would have updated the FCL status as follows: 


DSN FCLDSNST FCL3UPDT Comments 

SYS1.A 1 0 DSCBs returned from prior call 
SYS2.B 5 0 DSCB chain exceeds total buffers 
SYS3.C 1 0 DSCBs returned from prior call 
SYS4.D 1 1 DSCBs returned from this call 
SYS5.E 1 1 DSCBs returned from this call 
SYS6.F 2 1 Data set name not found 


FCLDSCBR would contain 4. (This CVAFFILT call returned a total of four 
DSCBs.) CVAF Filter would not return any DSCBs for SYS6.F, because its 
format-1 DSCB cannot be found on the volume (FCLDSNST = '2'). 


se Because this status indicates that CVAF Filter has returned all requested DSCBs, 
( . and you requested FLTAREA=KEEP and IOAREA=KEEP on the previous call, 
= you should request the RLSE function as follows: 


CVAFFILT ACCESS=RLSE, FLTAREA=NOKEEP , [OAREA=NOKEEP, 
MF=(E,CVPLIST) 


Obtaining Information from the VTOC Index 


You may use ACCESS=MAPDATA to obtain information contained in the space 
maps. ‘““CVAFDSM Macro” on page 239 discusses detailed information about the 
CVAFDSM VTOC access macro. 


To count the number of unallocated VIRs in the VTOC index space map (VIXM), 
you must code COUNT=YES and MAP=INDEX. CVAF returns the number of 
unallocated VIRs in the 4-byte area specified by the CTAREA keyword. 


To count the number of format-O0 DSCBs, you must code COUNT=YES and 
MAP=VTOC. CVAF returns the number of format-O DSCBs in the VTOC map 
of DSCBs VMDS in the 4-byte area specified by the CTAREA keyword. 


To obtain one or more free space extents from the VTOC pack space map 
(VPSM), you must code COUNT=NO and MAP=VOLUME. CVAF returns the 
extents in the area specified by the EXTENTS keyword. Each extent is returned in 
a 5-byte XX YYZ format, the same as for a format-5 DSCB extent, where XX is 
the relative track address (RTA) of the first track of the extent, YY is the number 
of whole cylinders in the extent, and Z is the number of additional tracks in the 
extent. The RTA specified by your program to CVAF in the first (or only) extent 
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serves as a Starting point for the VPSM search; the extent returned is the next free 
extent with a higher starting RTA than the one your program specified. ia 


If all the unallocated extents in the VPSM are supplied before filling in all the 
extents supplied, the remaining extents are set to zero. CVAF provides return code 
4 in register 15 and indicates end-of-data condition by putting a value of X'20' in 
the CVSTAT field. 


Diagnosing VTOC Errors 


Actions Taken When an Error Occurs 
These actions are taken if an error occurs: 


e If an index structure error is detected, DADSM or CVAF causes the VTOC 
index to be disabled. The indexed VTOC bit is zeroed in the format-4 DSCB. 
A software error record is written to SYS1.LOGREC. A system dump is 
taken. The VTOC is converted to a nonindexed format at the next DADSM 
allocate or extend call. 


e If a program check, machine check, or other error occurs while using a VTOC 
access macro, a SYS1.LOGREC message is written, and a system dump is 
taken. 


e Anerror code is put in the CVSTAT field of the CVPL. The values and 
explanations of these error codes are listed in Appendix C, ‘““WTOC Index a 
Error Message and Associated Codes”’ on page 297. | 


Recovering from System or User Errors 


Because an unauthorized user cannot modify a VTOC, neither the VTOC nor the 
VTOC index need be recovered from a user error caused by an unauthorized user. 


A system error affects a VTOC and VTOC index, probably by interrupting 
DADSM while it is updating, thus leaving the VTOC and/or the VTOC index ina 
partially updated state. Both the VTOC and the VTOC index are designed to 
allow DADSM to recover from such an interruption. 


For a nonindexed VTOC (or a VITOC with an index that has been disabled), a 
subsequent call to DADSM ALLOCATE or EXTEND causes VTOC convert 
routines to reestablish the free space (format-5 DSCBs). 


For an indexed VTOC, a subsequent call to any DADSM function causes the 
recovery of the previous interrupt (either by backing out or completing the 
interrupted function). 
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GTF Trace 
( A trace function exists to trace all CVAF calls for VTOC index output I/O, all 


VTOC output I/O, and all VTOC index and space map modifications. For 
information on this function, see DFP Diagnosis. 


Listing a VTOC and VTOC Index 


You may obtain dump, formatted, or abridged listings of the VTOC and the VTOC 
index by using the LISTVTOC command of the IEHLIST utility program. 
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Chapter 2. Executing Your Own Channel Programs (EXCP) 








The execute-channel-program (EXCP) macro instruction provides you with 
complete control of the data organization based on device characteristics. This 
chapter contains a general description of the function and application of the EXCP 
macro instruction, accompanied by descriptions of specific control blocks and 
macro instructions used with EXCP. Factors that affect the operation of EXCP, 
such as device variations and program modification, are also discussed. 


| 


reas 


Before reading this chapter, you should be familiar with system functions and with 
the structure of control blocks, as well as with the operational characteristics of the 
I/O devices required by your channel programs. Operational characteristics of 
specific I/O devices are described in IBM publications for each device. 





You also need to understand the information in these publications: 


e Data Administration Guide contains the standard procedures for I/O processing 
under the operating system. 


e Assembler H Version 2 Application Programming: Guide contains the 
information necessary to code programs in the assembler language. 


e Data Administration: Macro Instruction Reference describes the system macro 
instructions that can be used in programs coded in the assembler language. 


e Conversion Notebook describes the factors to consider when converting from 
MVS/370 at the MVS/SP Version 1 level to MVS/XA. 


The execute-channel-program (EXCP) macro instruction causes a supervisor-call 
interruption to pass control to the EXCP processor. (I/O process is the name we 
will use for the EXCP processor and the I/O supervisor. For our purposes, it’s 
unnecessary to understand how input/output processing is divided between the 
two.) EXCP also provides the I/O supervisor with control information regarding a 
channel program to be executed. When an IBM access method is being used, an 
access method routine is responsible for issuing EXCP. If you are not using an 
IBM access method, you must issue EXCP in your program. (The EXCP macro 
instruction cannot be used to process SYSIN or SYSOUT data sets.) 


You issue EXCP primarily for I/O programming situations to which the standard 
access methods do not apply. If you are writing your own access method, you must 
include EXCP for I/O operations. EXCP must be used for processing 
nonstandard labels, including reading and writing labels and positioning magnetic 
tape volumes. 


To issue EXCP, you must provide a channel program (a list of channel command 
words) and several control blocks in your program area. The I/O process then 
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schedules I/O requests for the device you have specified, executes the specified 
I/O commands, handles I/O interruptions, directs error recovery procedures, and 
posts the results of the I/O requests. 


Using EXCP in System and Problem Programs 


This section explains the procedures performed by the system and the programmer 
when EXCP is issued by the routines of IBM access methods. The additional 
procedures you must perform when issuing EXCP yourself are then described by 
direct comparison. 


How the System Uses EXCP 


When using an IBM access method to perform I/O operations, the programmer is 
relieved of coding channel programs and constructing the control blocks necessary 
for the execution of channel programs. To permit I/O operations to be handled by 
an access method, the programmer need only issue the following macro 
instructions: 


¢ A DCB macro instruction that produces a data control block (DCB) for the 
data set to be retrieved or stored 


e An OPEN macro instruction that initializes the data control block and 
produces a data extent block (DEB) for the data set 


e A macro instruction (for example, GET or WRITE) that requests I/O 
operations 


Access method routines will then: 


1. Create a channel program that contains channel commands for the I/O 
operations on the appropriate device 


2. Construct an input/output block (IOB) that contains information about the 
channel program 


3. Construct an event control block (ECB) that is later posted with a completion 
code each time the channel program terminates 


4. Issue an EXCP macro instruction to pass the address of the IOB to the routines 
that initiate and supervise the I/O operations 


The I/O process consists of: 

5. Constructing a request queue element (RQE) for scheduling the request 

6. If the requestor is ina V=V address space, fixing the buffers so that they 
cannot be paged out and translating the requestor’s virtual channel program 


into a real channel program 


7. Issuing a start subchannel (SSCH) instruction to cause the channel to execute 
the real channel program 
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8. Processing I/O interruptions and scheduling error recovery procedures when 
necessary 





9. Posting a completion code in the event control block after the channel program 
has been executed 


Note: If the requestor is an authorized program in a V=R address space, a real 
channel program is provided; thus, item 6 is not performed. 


The programmer is not concerned with these procedures and does not know the 
status of I/O operations until they are completed. Device-dependent operations 
are limited to those provided by the macro instructions of the particular access 
method selected. 


How To Use EXCP in Problem Programs 





To issue the EXCP macro instruction directly, you must follow the procedures that 
the access methods would perform, as summarized in items 1 through 4 of the 
preceding discussion. In addition to constructing and opening the data control 
block with the DCB and OPEN macro instructions, you must construct a channel 
program, an input/output block, and an event control block before you can issue 
EXCP. The I/O process generally handles items 5 through 9. 





After issuing EXCP, you should issue a WAIT macro instruction, specifying the 
address of the event control block, to determine whether the channel program has 
terminated. If volume switching is necessary, you must issue an EOV macro 
-_ instruction. When all processing of the data set has been completed, you must 
( issue a CLOSE macro instruction to restore the data control block. 


All external interfaces for EXCP are compatible between MVS/370 and 
MVS/XA, except for the restrictions noted below. These restrictions relate only to 
the support of virtual and real addresses above 16 megabytes. 


EXCP will be available to programs executing in either 24-bit or 31-bit addressing 
mode. However, in order to maintain the required compatibility, the following 
restrictions apply: 


e EXCP will only support a 24-bit virtual storage interface. In addition, all areas 
related to I/O operations (for example, I/O buffers, channel command words, 
IOBs, DEBs, appendages, and so forth), must remain 24-bit virtual 
addressable. EXCP (channel command word translator) will allow 24-bit 
virtual I/O buffers to be fixed above 16-megabyte real. When a channel 
command word (CCW) references a real address above 16-megabyte, the 
CCW translator will build an indirect addressing word (IDAW) for that CCW. 
Note that this is not supported for format-1 CCWs. All virtual addresses must 
be below 16-megabyte. For V=R users, CCWs and IDAWs must be below 
16-megabyte real. 


e Only format-0 CCWs are accepted as input. 


e All user-specified appendage routines are given control in 24-bit addressing 
mode and must return in the same mode. 





Chapter 2. Executing Your Own Channel Programs (EXCP) 65 








Note: Access methods run in 24-bit addressing mode. Users running in 31-bit ; 
mode must interface to the access methods by using a user-written routine that is af 
resident below 16-megabyte virtual (because the access methods will be able to eo 
return control only to a 24-bit addressable location). All addresses, buffers, 
parameters, control blocks, save areas and exit addresses must be below 
16-megabyte virtual. All access methods (except a for example, GET or 
PUT, must be called in 24-bit addressing mode. 


31-Bit IDAW Requirements 


A virtual channel program provided by the EXCP caller may have one or more 
CCWs with the IDA flag set and the address portion of these CCWs pointing to a 
single 4-byte IDAW. This EXCP function is referred to as virtual IDAWs. 


The 4-byte IDAW can contain a virtual address that ranges from 0 to the maximum 
31-bit address. Virtual IDAWs are supported on all virtual CCWs except: 


e Transfer in channel (TIC) commands. 


e All non data-transfer type commands: for example, recalibrate, rewind, set 
space, fold, block data check, no operation, control commands. 


e Read, read backward, and sense commands, with the skip flag set. 


The same addressing restrictions apply to EXCPVR inputs with the exception that 
31-bit real data areas may be specified by the user-created CC Ws through the use 7 
of IDAWs. All CCWs and IDAWs must be below 16-megabyte real. a 


. 


Pa 


Only format-0 CCWs are accepted as input. 


All other areas related to the EXCP/EXCPVR I/O operation (for example, 
CCWs, IDAWs, IOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
addressable. 


Note, however, that the EXCP processor will allow both 24-bit and 31-bit virtual 
I/O buffers to be fixed above 16-megabyte real. 


How EXCP Operates in a V=R Address Space 


User-constructed channel programs for I/O operations of an authorized program in 
a V=R address space are not translated. Because the address space is V=R, any 
CCWs created by the user have correct real data addresses. (Translation would 
only re-create the user’s channel program, so the CCWs are used directly.) 


Modification of an active channel program by data read in or by processor 
instructions is legitimate in a V=R address space, but not in a V=V address space. 
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EXCP Requirements 


Channel Program 


Control Blocks 


Input/Output Block (IOB) 


This section describes the channel program that you must provide in order to issue 
EXCP. This section also describes the control blocks that you must either directly 
construct or cause to be constructed by using macro instructions. 


All areas related to the EXCP/EXCPVR I/O operation (for example, CCWs, 
IDAWs, IOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
addressable. 


Note, however, that the EXCP processor will allow both 24-bit and 31-bit virtual 
I/O buffers to be fixed above 16-megabyte real. 


The channel program supplied by you and executed through EXCP is composed of 
CCWs on doubleword boundaries. Each channel command word specifies a 
command to be executed and, for commands initiating data transfer, the area to or 
from which the data is to be transferred. 


Channel command word operation codes used with specific I/O devices can be 
found in IBM publications for those devices. All channel command word operation 
codes described in these publications can be used. In addition, both data chaining 
and command chaining may be used. 


To specify either data chaining or command chaining, you must set appropriate bits 
in the channel command word and indicate the type of chaining in the input/output 
block. Both data and command chaining should not be specified in the same 
channel command word; if they are, data chaining takes precedence. 


EXCP does not support channel programs that modify themselves, regardless of 
the method of modification: data chaining, command chaining, or a program to do 
the modification. The intended modification in virtual storage has no effect on the 
running real-channel program (see “Modification of a Channel Program during 
Execution” on page 70). | 


When using EXCP, you must be familiar with the function and structure of the 
IOB, the ECB, the DCB, the DEB, and the IDAW. IOB and ECB fields are 
illustrated under “‘Control Block Fields” on page 88. DCB fields are illustrated 
under “‘Macro Specifications for Use with EXCP” on page 73. The handling of 
IDAWs is described under “‘SIO Appendage” on page 95. Descriptions of these 
control blocks follow. 


The input/output block is used for communication between the problem program 
and the system. It provides the addresses of other control blocks, and maintains 
information about the channel program, such as the type of chaining and the 
progress of I/O operations. You must define the input/output block and specify 
its address as the only parameter of the EXCP macro instruction. 
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Event Control Block (ECB) 


The event control block provides you with a completion code that describes bed 
whether the channel program was completed with or without error. A WAIT 

macro instruction, which can be used to synchronize I/O operations with the 

problem program, must identify the event control block. You must define the 
event control block and specify its address in the input/output block. 


Data Control Block (DCB) 


The data control block provides the system with information about the 
characteristics and processing requirements of a data set to be read or written by 
the channel program. A data control block must be produced by a DCB macro 
instruction that includes parameters for EXCP. If you are not using appendages, a 
short DCB is constructed. Such a DCB does not support reduced error recovery. 
You specify the address of the data control block in the input/output block. 


All DCBs must be located in storage that is not fetch-protected, or, if the task is 
authorized, in storage that is in the key of the task (TCB KEY). 


Data Extent Block (DEB) 


The data extent block contains one or more extent entries for the associated data 
set and other control information. An extent defines all or part of the physical 
boundaries on an I/O device occupied by, or reserved for, a particular data set. 
Each extent entry contains the address of a unit control block (UCB) that provides 
information about the type and location of an I/O device. More than one extent 
entry can contain the same UCB address. For all I/O devices supported by the 
operating system, the data extent block is produced during execution of the OPEN 
macro instruction for the data control block. The system places the address of the 
data extent block into the data control block. All DEBs must be located in storage 
that is not fetch-protected, or, if the task is authorized, in storage that is in the key 
of the task (TCB key). Only authorized tasks (APF-authorized or TCB PKF=0-7) 
may build DEBs to be used for I/O operations. 


How the Channel Program Executes 


This section explains how the system uses your channel program and control blocks 
after you issue EXCP. 


Initiation of the Channel Program 
By issuing EXCP, you request the execution of the channel program specified in 
the input/output block. The I/O process validates the request by checking certain 
fields of the control blocks associated with this request. If the I/O process detects 
invalid information in a control block, it initiates abnormal termination procedures. 


The EXCP processor gets: 


e The address of the data control block from the input/output block 





e The address of the data extent block from the data control block 
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e The address of the unit control block from the data extent block 


It places the IOB, TCB, DEB, and UCB addresses and other information about the 
channel program into an area called a request queue element (RQE). (Unless you 
are providing appendage routines (described under ‘‘Appendages”’ on page 71) 
you should not be concerned with the contents of RQEs.) 


If you have provided an SIO (start I/O) appendage, the EXCP processor now 
passes control to it. The return address from the SIO appendage determines 
whether the EXCP processor must: 


e« Execute the I/O operation normally, or 
e Skip the I/O operation. 


For a description of the SIO appendage and its linkage to the EXCP processor, see 
‘‘Appendages” on page 71. 


If you are issuing EXCP from a V=V address space, the channel program you 
construct contains virtual addresses. Because channel subsystems cannot use 
virtual addresses, the EXCP processor must: 


e Translate your virtual channel program into one that uses only real addresses. 


¢ Fix in real storage the pages used as I/O areas for the data transfer operations 
specified in your channel program. 


The EXCP processor builds the translated (real) channel program in a portion of 
real storage. 


For direct access devices, specify the seek address in the input/output block. The 
I/O supervisor constructs a CCW chain to issue the seek and the set file mask 
specified in the data extent block, and to pass control to your real channel program. 


If your channel program begins with a locate-record CCW, the I/O process builds 
a define-extent CCW and passes control to your real channel program. (You 
cannot issue the initial seek, set file mask, or define extent CCWs. The file mask is 
set to prohibit seek-cylinder CCWs, or, if space is allocated by tracks, seek-head 
commands. If the data set is open for INPUT, write CCWs are also prohibited.) 


For a magnetic tape device, the I/O supervisor constructs a CCW chain to set the 
mode specified in the data extent block and passes control to your real channel 
program. (You cannot set the mode yourself.) 


If the I/O device is other than a direct access device or a magnetic tape device, the 


I/O supervisor then places the starting CCW of the channel program into the 
operation request block (ORB) and issues a start subchannel (SSCH) instruction. 
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Modification of a Channel Program during Execution 


_ Any problem program that modifies an active channel program with processor 


instructions or with data read in by an I/O operation must be run ina V=R 
address space. It cannot run in a V=V address space because of the channel 
program translation performed by the I/O supervisor. (In a V=V address space, 
an attempt to modify an active channel program affects only the virtual image of 
the channel program, not the real channel program being executed by the channel 
subsystem.) 


A program of this type can be changed to run in a V=V address space by issuing 
another EXCP macro for the modified portion of the channel program. 


Completion of Execution 


The system considers the channel program completed when it receives an 
indication of a channel-end condition in the subchannel status word (SCSW). 
Unless a CHE (channel-end) or ABE (abnormal-end) appendage directs otherwise, 
the request queue element for the channel program is made available, and a 
completion code is placed into the event control block. The completion code 
indicates whether errors are associated with channel end. If device end occurs 
simultaneously with channel end, errors associated with device end (that is, unit 
exception or unit check) are also accounted for. 


If device end occurs after channel end and if an error is associated with device end, 
the completion code in the event control block does not indicate the error. 
However, the status of the unit and channel is saved by the I/O supervisor for the 
device, and the UCB is marked as intercepted. The input/output block for the 
next request directed to the I/O device is also marked as intercepted. The error is 
assumed to be permanent, and the completion code in the event control block for 
the intercepted request indicates interception. The DCBIFLGS field of the data 
control block is also flagged to indicate a permanent error. Note that, if a 
write-tape-mark or erase-long-gap CCW is the last or only CCW in your channel 
program, the I/O process will not attempt recovery procedures for device end 
errors. In these circumstances, command chaining a NOP CCW to your 
write-tape-mark or erase-long-gap CCW ensures initiation of device-end error 
recovery procedures. | 


To be prepared for device-end errors, you should be familiar with device 
characteristics that can cause such errors. After one of your channel programs has 
terminated, you should not release buffer space until you have determined that 
your next request for the device has not been intercepted. You may reissue an 
intercepted request. 


Interruption Handling and Error Recovery Procedures 


An I/O interruption allows the processor to respond to signals from an I/O device 
that indicate either termination of a phase of I/O operations or external action on 
the device. A complete explanation of I/O interruptions is contained in JBM 
System/370 Principles of Operation. For descriptions of interruption by specific 
devices, see the IBM publications for each device. 
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Appendages 


If error conditions are associated with an interruption, the I/O supervisor schedules 
the appropriate device-dependent error routine. The channel subsystem is then 
restarted with another request that is not related to the channel program in error. 
(The following paragraphs discuss ‘“‘related’’ channel programs.) If the error 
recovery procedures fail to correct the error, the system places ones in the first two 
bit positions of the DCBIFLGS field of the data control block. You are informed 
of the error by an error code in the event control block. 


If a channel program depends on the successful completion of a previous channel 
program (as when one channel program retrieves data to be used in building 
another), the previous channel program is called a “‘related’”’ request. Such a 
request must be identified to the EXCP processor. To find out how to do this, see 
“Input/Output Block (IOB) Fields” on page 89 and “Purging and Restoring I/O 
Requests” on page 156. 


If a permanent error occurs in the channel program of a related request, the EXCP 
processor removes the request queue elements for all dependent channel programs 
from their queue and makes them available. 


The related request queue (RRQ) reflects the order in which request queue 
elements are removed from their queue. 


For all requests dependent on the channel program in error, the system places 
completion codes into the event control blocks. The DCBIFLGS field of the data 
control block is also flagged. Any requests for a data control block with error flags 
are posted complete without execution. To reissue requests dependent on the 
channel program in error, you must reset the first two bits of the DCBIFLGS field 
of the data control block to zeros. You then reissue EXCP for each channel 
program desired. 


With the IBM 3800 Printing Subsystem, a cancel key or a system-restart-required 
paper jam causes both a lost data indicator to be set in DCBIFLGS and a lost page 
count and channel page identifier to be stored in the UCB extension. (See JES3 
Data Areas, TSO/E Data Areas, and IBM 3800 Printing Subsystem Programmer's 
Guide.) 


The detailed information about appendages that appeared in this section has been 
moved to Data Facility Product: Customization. 


An appendage is a user-written routine that provides additional control over I/O 


operations. By using appendages, you can examine the status of I/O operations 
and determine the actions to be taken for various conditions. 


Chapter 2. Executing Your Own Channel Programs (EXCP) 71 




















Channel Programming Considerations _ 


i 

Command retry is a function of the channel supporting the IBM 2305-2, ia 
3330/3333, 3340/3344, 3350, 3375, and 3380 direct access devices. When the 
channel subsystem receives a retry request, it repeats the execution of the CCW, 
requiring no additional input/output interrupts. For example, a control unit may 
initiate a retry procedure to recover from a transient error. 
A command retry during the execution of a channel program may cause any of the 
following conditions to be detected by the initiating program: 
e Modifying CCWs: A CCW used in a channel program must not be modified 

before the CCW operation has been successfully completed. Without the 

command retry function, a command was fetched only once from storage by a 

channel. Therefore, a program could determine through condition codes or 

program controlled interruptions (PCI) that a CCW had been fetched and 

accepted by the channel. This permitted the CCW to be modified before 

reexecution. With the command retry function, this cannot be done, because 

the channel will fetch the CCW from storage again on a command retry 

sequence. In the case of data chaining, the channel will retry commands 

starting with the first CCW in the data chain. 
e Program Controlled Interrupts (PCI): A CCW containing a PCI flag may cause 

multiple program-controlled interrupts to occur. This happens if the 

PCI-flagged CCW was retried during a command retry procedure and if a PCI 

could be generated each time the CCW is reexecuted. e 
e Residual Count: If a channel program is prematurely terminated during the ae, 


retry of a command, the residual count in the channel status word (CSW) will 
not necessarily indicate how much storage was used. For example, if the 
control unit detects a “‘wrong-length record” error condition, an erroneous 
residual count is stored in the CSW until the command retry is successful. 
When the retry is successful, the residual in the CSW reflects the correct length 
of the data transfer. 


e Command Address: When data chaining with command retry, the CSW may 
not indicate how many CCWs have been executed at the time of a PCI. For 


example: 

CCW# Channel Program 

1 Read, data chain 

2 Read, data chain 

3 Read, data chain, PCI 
4 Read, command chain 


In this example, assume that the control unit signals command retry on Read 
#3 and the processor accepts the PCI after the channel resets the command 
address to Read #1 because of command retry. The CSW stored for the PCI 
will contain the command address of Read #1 when the channel has actually 
progressed to Read #3. 


e Testing Buffer Contents on Data Read: Any program that tests a buffer to 
determine when a CCW has been executed and continues to execute based on 
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this data may get incorrect results if an error is detected and the CCW is 


( ; retried. 
Macro Specifications for Use with EXCP 


If you are using the EXCP macro instruction, you must also use DCB, OPEN, 
CLOSE, and, in some cases, the EOV macro instruction. The parameters.of the 
DCB, EOV, and EXCP macro instructions are described here. The parameters and 
different forms of the OPEN and CLOSE macro instructions are described in Data 
Administration: Macro Instruction Reference. A diagram of the data control block 





(DCB) is included in this section with the description of the DCB macro 
instruction. 


Defining Data Control Blocks for EXCP (DCB) 


The EXCP form of the DCB macro instruction produces a data control block that 
can be used with the EXCP macro instruction. You must issue a DCB macro 
instruction for each data set to be processed by your channel programs. (Notation 
conventions and format illustrations of the DCB macro instruction are given in 
Data Administration: Macro Instruction Reference.) DCB parameters that apply to 
EXCP may be divided into four categories, depending on the following portions of 
the data control block that are generated when they are specified: 


e Foundation block. This portion is required and is always 12 bytes in length. 
( % You must specify two of the parameters in this category. 


e EXCP interface. This portion is optional. If you specify any parameter in this 
category, 20 bytes are generated. 


e Foundation block extension and common interface. This portion is optional 
and is always 20 bytes in length. If this portion is generated, the 
device-dependent portion is also generated. 


e Device dependent. This portion is optional and is generated only if the 
foundation block extension and common interface portion is generated. Its 
size ranges from 4 to 20 bytes, depending on specifications in the DEVD 
parameter. However, if you do not specify the DEVD parameter (and the 
foundation extension and common interface portion is generated), the 
maximum 20 bytes for this portion are generated. 


Some of the procedures performed by the system when the data control block is 
opened and closed (such as writing file marks for output data sets on direct access 
volumes) require information from optional data control block fields. You should 
make sure that the data control block is large enough to provide all information 
necessary for the procedures you want the system to handle. 


Figure 20 on page 75 shows the relative position of each portion of an opened 
data control block. The fields corresponding to each parameter of the DCB macro 
instruction are also designated, with the exception of DDNAME, which is not 
included in a data control block that has been opened. The fields identified in 
parentheses represent system information that is not associated with parameters of 
the DCB macro instruction. 
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Sources of information for data control block fields other than the DCB macro 
instruction are data definition (DD) statements, data set labels, and data control 
block modification routines. You may use any of these sources to specify DCB 
parameters. However, if a particular portion of the data control block is not 
generated by the DCB macro instruction, the system does not accept information 
intended for that portion from any alternative source. 


You may provide symbolic names for the fields in one or more EXCP DCBs by 
coding a DCBD macro to generate a dummy control section (DSECT). To map 
the common interface, foundation block extension, and foundation block, you code 
DSORG=XE. To map the foundation block and EXCP interface, you code 
DSORG=XA. You may code DSORG=(XA,XE) to map both. For further 
information, see Data Administration: Macro Instruction Reference. 


Foundation Block Parameters 


DDNAME=symbol 
The name of the data definition (DD) statement that describes the data set 
to be processed. This parameter must be given. 


MACRF=(E) 
The EXCP macro instruction is to be used in processing the data set. This 
operand must be coded. 


REPOS={Y | N} 
Magnetic tape volumes: This parameter indicates to the dynamic device 
reconfiguration (DDR) routine whether the user is keeping an accurate block 
count. If the user is keeping an accurate block count, the DDR routine can 


attempt to swap the volume. (You must maintain the block count in the 
DCBBLKCT field.) 


Y—The user is keeping an accurate block count, and the DDR routine can 
attempt to swap the volume. 


N—tThe block count is unreliable, and the DDR routine cannot and will not 
attempt to swap the volume. 


If the operand is omitted, N is assumed. 
EXCP Interface Parameters 

EOEA=symbol 
2-byte identification of an EOE appendage that you have entered into 
SYS1.LPALIB or SYS1.SVCLIB. 

PCIA=symbol 
2-byte identification of a PCI appendage that you have entered into 
SYS1.LPALIB or SYS1.SVCLIB. 

SIOA=symbol 


2-byte identification of a SIO appendage that you have entered into 
SYS1.LPALIB or SYS1.SVCLIB. 
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| 0 | 
The device—dependent portion of the data control 


_ block varies in length and format according to 
specifications in the DSORG and DEVD parameters. 
lllustrations of this portion for each device 
type are included in the description of the DEVD 
parameter. 


Device 
Dependent 





Common 
Interface 


32 BFTEK, 
BFALN Foundation 
Block 


Extension 


Foundation 
Block 





EXCP 


EOEA Interface 


SIOA 


ee ee a ee ee a) See es a a a ee ee, eee 


XENDA Reserved 


Figure 20. Data Control Block (DCB) Format for EXCP (After OPEN) 





CENDA=symbol 
2-byte identification of a CHE appendage that you have entered into 
SYS1.LPALIB or SYS1.SVCLIB. 


XENDA=symbol 
2-byte identification of an ABE appendage that you have entered into 
SYS1.LPALIB or SYS1.SVCLIB. 
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OPTCD=Z 
indicates that, for magnetic tape (input only), a reduced error recovery P aaa 
procedure (5 reads only) will occur when a data check is encountered. It 
should be specified only when the tape is known to contain errors and the 
application does not require that all records be processed. Its proper use 
would include error frequency analysis in the SYNAD routine. Specification 
of this parameter will also cause generation of a foundation block extension. 
This parameter is ignored unless it was selected at system generation. 


IMSK= value 
Any specification indicates that the system will not use IBM-supplied error 
routines. 


Foundation Block Extension and Common Interface Parameters 


EXLST=address 
the address of an exit list that you have written for exception conditions. The 
format of the exit list is provided in Data Facility Product: Customization. 


EODAD=address 
the address of your end-of-data-set routine for input data sets. If this 
routine is not available when it is required, the task is abnormally terminated. 


DSORG=3PS | PO | DA | IS} 
the data set organization (one of the following codes). Each code indicates 
that the format of the device-dependent portion of the data control block is 
to be similar to that generated for a particular access method: 


Code DCB Format for ae. 


PS QSAM or BSAM 
PO BPAM 

DA BDAM 

Is QISAM or BISAM 


For direct access devices, if you specify PS or PO, you must maintain the 
following fields of the device-dependent portion of the data control block so 
that the system can write a file mark for output data sets: 


e The track balance (DCBTRBAL) field that contains a 2-byte binary 
number that indicates the remaining number of bytes on the current 
track. This number can be obtained from the system track algorithm 
routine. 


¢« The full disk address (DCBFDAD) field that indicates the location of 
the current record. The address is in the form MBBCCHHR. 


These fields are written into the format-1 DSCB and are used by Open 
routines for staging MSS data sets. Staging is done only up through the last 
cylinder specified by these fields if the data set is reopened for OUTPUT, 
INOUT, OUTIN, OUTINX, or EXTEND. 


If you specify PO for a direct access device, the DCBDIRCT field will not be 
updated. Therefore, you should be careful when using EXCP with the 
STOW macro. 
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IOBAD=address 
the address of an input/output block (IOB). If a pointer to the current IOB 
is not required, you may use this field for any purpose. 





The following parameters are not used by the EXCP routines. They provide 
additional information that the system will store for later use by access methods 
that read or update the data set. 


RECFM=code 
the record format of the data set. (Record format codes are given in Data 
Administration: Macro Instruction Reference.) When writing a data set to be 
read later, RECFM, LRECL, and BLKSIZE should be specified to identify 
the data set attributes. LRECL and BLKSIZE can only be specified in a DD 
statement, because these fields do not exist in a DCB used by EXCP. 


BFTEK=3$S | E} 
the buffer technique, either simple or exchange. 


BFALN= %F | D} 
the word boundary alignment of each buffer, either fullword or doubleword. 


BUFL=length 
the length in bytes of each buffer; the maximum length is 32767. 


BUFNO=number 
the number of buffers assigned to the associated data set; the maximum 
— number is 255. See Chapter 10, “‘Specifying Buffer Numbers for DASD 
( . Data Sets’ on page 229, for further details and performance considerations. 


BUFCB=address 
the address of a buffer pool control block, that is, the 8-byte field preceding 
the buffers in a buffer pool. 


Device-Dependent Parameters 
DEVD=code 


the device in which the data set may reside. The codes are listed in order of 
descending space requirements for the data control block: 


Code Device 

DA Direct access 
TA Magnetic tape 
PR Printer 

PC Card punch 
RD Card reader 


Note: For MSS virtual volumes, DA should be used. 


If you do not want to select a specific device until job setup time, you should 
specify the device type requiring the largest area; that is, DEVD=DA. 


The following diagrams illustrate the device-dependent portion of the data control 
block for each combination of device type specified in the DEVD parameter and 
data set organization specified in the DSORG parameter. Fields that correspond to 
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device-dependent parameters in addition to DEVD are indicated by the parameter 
name. For special services, you may have to maintain the fields shown in 
parentheses. The special services are explained in the note that follows the 
diagram. : 


Device-dependent portion of data control block when DEVD=DA and 
DSORG=PS: 









4 





Reserved DCBFDAD 


13 
DCBDVTBL 
16 17 18 
DCBKEYLE DCBDEVT DCBTRBAL 


For output data sets, the system uses the contents of the full disk address 
(DCBFDAD) field, plus one, to write a file mark when the data control block is 
closed, provided the track balance (DCBTRBAL) field indicates that space is 
available. If DCBTRBAL is less than 8, the file mark is written on the next 
sequential track. You must maintain the contents of these two fields yourself if the 
system is to write a file mark. OPEN will initialize DCBDVTBL and DCBDEVT. 





Device-dependent portion of data control block when DEVD=DA and 
DSORG=DA: 


16 18 
DCBKEYLE Reserved 


Device-dependent portion of data control block when DEVD=TA and 
DSORG=PS: 


12 

DCBBLKCT 
16 17 18 19 
DCBTRTCH Reserved DCBDEN Reserved 


The system uses the contents of the block count (DCBBLKCT) field to write the 
block count in trailer labels when the data control block is closed or when the EOV 
macro instruction is issued. You must maintain the contents of this field yourself if 
the system is to have the correct block count. (Note: The I/O supervisor 
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increments this field by the contents of the IOBINCAM field of the IOB at the 
completion of each I/O request.) 


When using EXCP to process a tape data set open at a checkpoint, you must be 
careful to maintain the correct count; otherwise, the system may position the data 
set incorrectly when restart occurs. If REPOS=Y, the count must be maintained 
by you for repositioning during dynamic device reconfiguration. 


Device-dependent portion of data control block when DEVD=PR and 


16 18 
DCBPRTSP Reserved 


Device-dependent portion of data control block when DEVD=PC or RD and 
DSORG=PS: 


16 18 


The following DCB operands pertain to specific devices and may be specified only 
when the DEVD parameter is specified. 


KEYLEN=/length 
for direct access devices, the length in bytes of the key of a physical record, 
with a maximum value of 255. When a block is read or written, the number 
of bytes transmitted is the key length plus the record length. 


DEN= value 
for magnetic tape, the tape recording density in bits per inch: 


Density 


Value 7-track tape device 9-track tape device 


1 556 — 

2 800 800 (NZRI) 
3 —_ 1600 (PE) 

4 ~— 6250 (GCR) 


NRZI—Non-return-to-zero change to ones recording 
PE—phase encoded recording 
GCR—group coded recording 


If this parameter is omitted, the highest density available on the device is 
assumed. 


TRTCH= value 
for 7-track magnetic tape, the tape recording technique: 
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Value Tape Recording Technique 


C Data conversion feature is available. 
E Even parity is used. (If omitted, odd parity is assumed.) 
T BCDIC to EBCDIC translation is required. 

MODE= value 


for a card reader or punch, the mode of operation. Either C (column binary 
mode) or E (EBCDIC code) may be specified. 


STACK= value 


for a card punch or card reader, the stacker bin to receive cards, either 1 or 
2. 


PRTSP= value 
for a printer, the line spacing, either 0, 1, 2, or 3. 


DSORG Parameter of the DCBD Macro 


In addition to the operands described in Data Administration: Macro Instruction 
Reference for the DSORG parameter of the DCBD macro, you may specify the 
following operands. 


DSORG= 
XA_ specifies a DCB with the EXCP interface section (including appendage 
names) - 
—_— 
XE specifies a DCB with the foundation block extension ae 


Initializing Data Control Blocks (OPEN) 


The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. You must issue OPEN for all data 
control blocks that are to be used by your channel programs. (A dummy data set 
may not be opened for EXCP.) Some of the procedures performed when OPEN is 
executed are: 


e Reading in the JFCB (job file control block), unless the TYPE=J option of the 
macro instruction was coded 


e Construction of the data extent block (DEB) 

e Transfer of information from the JFCB and data set labels to the DCB 
e Verification or creation of standard labels 

e Tape positioning 

e Loading of your appendage routines 


The parameters and different forms of the OPEN macro instruction are described 
in Data Administration: Macro Instruction Reference. 
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If you intend to process a multivolume direct data set, you must cause the open 
routines to build a data extent block for each volume and issue mount messages for 
them. This can be done by reading in the JFCB with a RDJFCB macro instruction 
and opening each volume of the data set. See ‘‘ Using RDJFCB to Process a 
Multivolume Direct Data Set” on page 141 for an example of how to code a 
routine to do this, and ““Reading and Modifying a Job File Control Block” on 

page 136 for further uses of the RDJFCB macro. 


Executing a Channel Program (EXCP) 


End of Volume (EOV) 


The EXCP macro instruction requests the initiation of the I/O operations of a 
channel program. You must issue EXCP whenever you want to execute one of 
your channel programs. The format of the EXCP macro instruction is: 


iob-addr—A-type address, (2-12), or (1) 
the address of the input/output block of the channel program to be 
executed. 


The EOV macro instruction identifies end-of-volume and end-of-data-set 
conditions. For an end-of-volume condition, EOV causes switching of volumes 
and verification or creation of standard labels. For an end-of-data-set condition, 
EOV causes your end-of-data set routine to be entered. Before processing trailer 
labels on a tape input data set, you must decrement the DCBBLKCT field. Your 
program issues EOV if switching of magnetic tape or direct access volumes is 
necessary, or if secondary allocation is to be performed for a direct access data set 
opened for output. 


For magnetic tape, you must issue EOV when either a tapemark is read or a 
reflective spot is written over. In these cases, bit settings in the 1-byte 
DCBOFLGS field of the data control block determine the action to be taken when 
EOV is executed. Before issuing EOV for magnetic tape, you must make sure that 
appropriate bits are set in DCBOFLGS. Bit positions 2, 3, 6, and 7 of 
DCBOFLGS are used only by the system; you are concerned with bit positions 0, 
1,4, and 5. The use of these DCBOFLGS bit positions is as follows: 


Bit 0 
set to 1 indicates that a write command was executed and that a tapemark is 
to be written. 


Bit 1 
indicates that a backward read was the last I/O operation. 


Bit 4 
indicates that data sets of unlike attributes are to be concatenated. 


Bit 5 
indicates that a tapemark has been read. 
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If bits 0 and 5 of DCBOFLGS are both off when EOV is executed, the tape is 
spaced past a tapemark, and standard labels, if present, are verified on both the old A 
and new volumes. The direction of spacing depends on bit 1. If bit 1 is off, the eo 
tape is spaced forward; if bit 1 is on, the tape is backspaced. . 


If bit 0 is on, but bit 5 is off, when EOV is executed, a tapemark is written 
immediately following the last data record of the data set. Standard labels, if 
specified, are created on the old and the new volume. 


After issuing EOV for sequentially organized output data sets on direct access 
volumes, you can determine whether additional space was obtained on the same or 
a different volume. You do this by examining the data extent block (DEB) and the 
unit control block (UCB). If neither the address of the UCB, as shown in the 
DEB, nor the volume serial number, as shown in the UCB, has changed, additional 
space was obtained on the same volume. Otherwise, space was obtained on a 
different volume. 


The parameters of the EOV macro instruction are: 


[symbol] EOV (dcb addr | acb addr) 

[.MODE=}24 | 313] 

dcb addr | acb addr—A-type address, (2-12), or (1) 
the address of the data control block or access method control block that is 


opened for the data set. If this parameter is specified as (1), register 1 must 
contain this address. 


MODE={24 | 31} es a 
indicates whether the EOV parameter list may reside above or below the 16 
megabyte line in virtual storage. The modes are: 


24 
If you do not specify the MODE operand, this mode is assumed. The 
expansion of the EOV macro generates a parameter list of the 
standard form (4 bytes per entry). The parameter list must be below 
the 16 megabyte line, but the calling program may be above the line. 
If your program is in 24-bit mode and you do not use a register to 
provide the address of the DCB or ACB, the DCB or ACB must be 
below the 16 megabyte line. 


31 
The expansion of the EOV macro generates a parameter list in the 
31-bit addressing mode format (8 bytes per entry). The parameter list 
may reside above or below the 16 megabyte line. The first byte (byte 
0) in each entry contains option information and the last four bytes 
(bytes 4-7) contain the 4-byte DCB or ACB address. The DCB (and 
all ACBs except VSAM/VTAM ACBs) must be below the 16 
megabyte line; therefore, byte 4 must be zeros. Bytes 1 through 3 must 
also be zeros. 


Note: Failure to provide a DCB below the 16 megabyte line causes an 
ABEND 50D. 
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Note: To determine how the system disposes of a tape volume when an EOV 
| macro is issued, see the description of the DISP parameter of the OPEN macro in 
| Data Administration: Macro Instruction Reference. 





Restoring Data Control Blocks (CLOSE) 


The CLOSE macro instruction restores one or more data control blocks so that 
processing of their associated data sets can be terminated. You must issue CLOSE 
for all data control blocks that were used by your channel programs. Some of the 
procedures performed when CLOSE is executed are: 


e Release of data extent block (DEB) 


e Removal of information transferred to data control block fields when OPEN 
was executed 





e Verification or creation of standard labels 


e Volume disposition 





e Release of programmer-written appendage routines | 


When CLOSE is issued for data sets on magnetic tape volumes, labels are 
processed according to bit settings in the DCBOFLGS field of the data control 
block. Before issuing CLOSE for magnetic tape, you must set the appropriate bits 
7 in DCBOFLGS. The significant DCBOFLGS bit positions are listed in the EOV 
( | macro instruction description. 


The parameters and different forms of the CLOSE macro instruction are described 
in Data Administration: Macro Instruction Reference. 


Assigning an Alternate Track and Copying Data from the Defective Track (ATLAS) 


A program that uses the EXCP macro instruction for input and output and that is 
APF authorized may, during the execution of the program, use the ATLAS macro 
instruction to obtain an alternate track and to copy a defective track onto the 
alternate track. With the use of ATLAS, the program can recover from permanent 
(hard) errors encountered in the execution of the following types of I/O 
commands: 


e Search ID. 


e Write. (The error condition must be confirmed during the execution of the 
channel program by a CCW that checks the data written.) 


e Read count. Errors in the CCHHR part of the count area can be recovered 
from, unless the record is the home address or record zero. Errors in the KDD 
part of the count area cannot be recovered from, unless the user has identified 
the defective record. 


Note: ATLAS may be used for all direct access devices with the exception of MSS 
volumes (3330V). 
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Your DCB must include the DCBRECFM field, and the field must show whether 
the data set is in the track overflow format. If it is, recovery from errors in last ae 
records on tracks depends on your identifying the track overflow record segments. ee 


oo ~ 


Recovery takes the form of obtaining a good alternate track and copying the 
defective track onto the good alternate one. Unless a reexecution of the channel 
program by ATLAS can correct the defect, the user should examine, and if 
necessary replace, defective records in a subsequent job if the data set is to be 
processed again. 


The format is: 


| | [symbol] ATLAS PARMADR=jaddr} 
[,CHANPRG=§R | NR}] 


[.CNTPTR={P | F3] 
[,WRITS={YES | NO}] 





PARMADR 
Address of a parameter address list of the following format: 


Address of |0B for the channel program that 
encountered the error 


Address of count area field 





The count area field contains the CCHHRKDD of a defective record or the 
CCHH of a track that is to be copied. 


addr—A -type address, (2-12), or (1) 


CHANPRG=3R | NR} | 
specifies whether the channel program that encountered the error can be 
executed again. 


R Channel program may be executed again by ATLAS. Before 
permitting reexecution of the channel program by ATLAS, you must 
reset the error indications of the previous execution fields in the 
DCBIFLGS. (See the example of the use of ATLAS below.) 


NR Channel program may not be executed again. 
If this parameter is omitted, R is assumed. 
CNTPTR 


specifies whether the count area field contains a full count area 
(CCHHRKDD) or a partial count area (CCHH). 
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Using ATLAS 


P Part of the count area (the CCHH address of the track to be copied). 


F Full count area (CCHHRKDD count of the record that was found 
defective). 


If this parameter is omitted, P is assumed. 


WRITS 
track overflow segment identification. 


If your data set is in the track overflow format, this identification determines 
recovery from errors in last records on tracks. 


YES If this is the last record on the track, it is a segment other than the last 
of a track overflow record. 


NO If this is the last record on the track, it is the last or only segment of a 
track overflow record. 


If this parameter is omitted, it is assumed that it cannot be established 
whether a last record is a segment of an overflow record. 


If a channel program encounters a unit check condition (shown in the CSW) in its 
execution, the EXCP processor program will place the sense bytes in the IOB. 
ATLAS can be used to recover from sense conditions shown by the following bit 
settings: 


IOBSENSO x'O8s! Data check 


IOBSENS 1 x'so' Permanent 


Also, before using ATLAS, you must reset error indications as follows: 


NI DCBIFLGS,X'3F' Reset the DCBIFLGS error indications. 


The ATLAS program will attempt to find a good alternate track and will attempt to 
copy the defective track onto the good track, including all error conditions in either 
key or data areas. The error conditions may be rectified by reexecuting the 
channel program or through the use of the IEHATLAS utility program in a 
subsequent step. 


Example: The following illustrates the use of the ATLAS macro instruction. 


Chapter 2. Executing Your Own Channel Programs (EXCP) 85 














EXCP MYIOB a, 
WAIT ECB=MYECB 
T™ MYECB,X'7F' TEST FOR I/O ERROR 
BO NEXT NO, SUCCESSFUL, GO TO 
* ANOTHER ROUTINE 
T™ IOBCSW+3,X'02' UNIT CHECK 
BZ OTHER NO, DO OTHER ERROR 
* PROCESSING 
TM IOBSENSO,X'08' DATA CHECK 
BNO OTHER NO, CAN'T HANDLE 
TM TOBSENS1,X'80! PERMANENT 
BNO OTHER NO, CAN'T HANDLE 
NI DCBIFLGS ,X'3F'! RESET ERROR 
* INDICATORS 
ATLAS PARMADR=THERE , CHANPRG=R 


Operation of the ATLAS Program 
The ATLAS program (SVC 86): 


e Establishes the availability and address of the next alternate track from the 
format-4 DSCB of the VTOC. 


e Brings all count fields from the defective track into storage to establish the 
description of the track. a & 


e Initializes the alternate track. (Writes the home address and record zero.) ars 


e Brings the key and data areas of each record into storage, one at a time, and 
combines them with their new count area to write the complete record onto the 
alternate track. 


e When the copying is finished, chains the alternate to the defective track and 
updates the VTOC. 


Control is returned to your program at the next executable instruction following the 
ATLAS macro instruction. 


Return Codes from the ATLAS Program 


The success of the ATLAS macro instruction can be determined by examining the 
contents of register 15, which will contain one of the return codes described below. 
If register 15 contains decimal 0, 36, 40, or 44, the contents of register 0 may be 
significant. 
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Code 


0(X'00') 


4(X'04') 


8(X'08') 


12(X'0C') 


16(X'10') 


20(X'14') 


24(X'18') 


28(X'1C') 


32(X'20') 


36(X'24') 


40(X'28') 


Meaning 


Successful completion. Key and data areas have been copied from 
the defective track onto a good alternate one. The only error 
encountered was in the record identified by the user’s CCHHRKDD 
value. 


If the channel program is reexecutable, it has been successfully 
reexecuted. 


This device type does not have alternate tracks that can be assigned 
by programming. 


All alternate tracks for the device have been assigned. 


A request for storage (GETMAIN macro instruction) could not be 
satisfied. 


All attempts to initialize and transfer data to an alternate track failed. 
The number of attempts made is equal to 10% of the assigned 
alternates for the device. 


The type of error shown by the sense byte cannot be handled 
through the use of the ATLAS macro instruction. The condition is 
other than a data check (in the count or data areas) or a missing 
address marker. 


The format-4 DSCB of the VTOC cannot be read; therefore 
alternate track information is not available to ATLAS. 


The record specified by the user was the format-4 DSCB, and it 
could not be read. 


An error found in count area of last record on the track cannot be 
handled because last-record-on-track identification is not supplied. 


An error was encountered when reading or writing the home address 
record or record zero. No error recovery has taken place. 


If register 0 contains X'01 00 OO OO', the defect is in record zero. 
Successful completion. Key and data areas have been copied from 
the defective track onto a good alternate one. However, the alternate 


track may have records with defective key or data areas. Register 0 
identifies the first three found defective as follows: 


nRRR 


n—The number of record numbers that follow (0, 1, 2, or 3). 
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Code Meaning 


R—The hexadecimal number of the record found defective but 
copied anyway. 


If the channel program is reexecutable, it has been successfully 
reexecuted. 


44(X'2C') _ Errors encountered and no alternate track has been assigned. The 
return parameter register (register 0) will contain the R of a 
maximum of three error records. 


Error conditions that return this code are: 


e ATLAS received an error indication for a record with a data 
length in the count field of zero. Recovery was not possible 
because a distinction cannot be made between an EOF record 
and an invalid data length. 


e Anerror occurred while reading the count field of a record, and 
the KDD (key length-data length) was found to be defective. 


e More than three records on the specified track contained errors 
in their count fields. 


48(X'30') Noerrors found on the track, no alternate assigned. ATLAS will not 
assign an alternate unless a track has at least one defective record. a 


52(X'34') I/Oerror in reexecuting user’s channel program. A good alternate is 
chained to the defective track, and data has been transferred. The 
user’s control blocks will give indication of the error condition 
causing failure in reexecution of the channel program. 


56(X'38') The DCB reflects a track overflow data set, but the UCB device type 
, shows that the device does not support track overflow. 


60(X'3C') The CCHH of the user-specified count area is not within the extents 
of the data set. 


64(X'40') The device is an MSS virtual device, which is not supported. 


Control Block Fields 


The fields of the input/output block, event control block, and data extent block are 
illustrated and explained here; the data control block fields are described with the 
parameters of the DCB macro instruction under ““EXCP Requirements” on 

page 67. 
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Input/Output Block (IOB) Fields 


( The input/output block (IOB) is not automatically constructed by a macro 
instruction; it must be defined as a series of constants and must be on a fullword 
boundary. For unit-record and tape devices, the IOB is 32 bytes in length. For 
direct access, teleprocessing, and graphic devices, 8 additional bytes must be 
provided. You may want to use the system mapping macro IEZIOB, which 
expands into a DSECT, to help in constructing an IOB. 


In Figure 21 on page 90 the diagonally ruled areas indicate fields in which you 
must specify information. The other fields are used by the system and must be 
defined as all zeros. You may not place information into these fields, but you may 
examine them. 


IOBFLAGI1 (1 byte) 
You must set bit positions 0, 1, and 6. One-bits in positions 0 and 1 indicate 
data chaining and command chaining, respectively. (If both data chaining 
and command chaining are specified, the system does not use error recovery | 
routines except for the direct access devices.) A one-bit in position 6 
indicates that the channel program is not a “‘related’’ request; that is, the 
channel program is not related to any other channel program. If you intend 
to issue an EXCP macro with a BSAM, OSAM, or BPAM data control 
block, you may want to turn on bit 7 to prevent access-method appendages 
from processing the I/O request. 








IOBFLAG2 (1 byte) 
co If you set bit 6 in the IOBFLAGI field to zero, bits 2 and 3 in this field must 
( then be set to: 


e 00, if any channel program or appendage associated with a related 
request might modify this IOB or channel program. 


e« 01, if the conditions requiring a 00 setting don’t apply, but the CHE or 
ABE appendage might retry this channel program if it completes 
normally or with the unit-exception or wrong-length-record bits on in 
the CSW. 


e 10 in all other cases. 


The three combinations of bits 2 and 3 represent the three kinds of related 
requests, known as type 1 (00), type 2 (01), and type 3 (10). The type you 
use determines how much the EXCP processor can overlap the processing of 
related requests. Type 3 allows the greatest overlap, normally making it 
possible to quickly reuse a device after a channel-end interruption. (Related 
requests that were executed on a pre-MVS system are executed as type-1 
requests if not modified.) 


IOBSENSO and IOBSENS1 (2 bytes) 
are placed into the input/output block by the EXCP processor when a unit 
check occurs. On occasion, the system is unable to obtain any sense bytes 
because of unit checks when sense commands are issued. In this case, the 
system simulates sense bytes by moving X'1OFE' to IOBSENSO and 
IOBSENS1. 
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Figure 21. Input/Output Block (IOB) Format 


IOBECBCC (1 byte) 
the first byte of the completion code for the channel program. The system 
places this code in the high-order byte of the event control block when the 
channel program is posted complete. The completion codes and their 
meanings are listed under ‘‘Event Control Block (ECB) Fields” on page 92. 


IOBECBPT (3 bytes) 
the address of the 4-byte event control block you have provided. 


IOBFLAG3 (1 byte) 
is used only by the system. 
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IOBCSW (7 bytes) 
the low-order seven bytes of the channel status word that are placed into this 
field each time a channel-end or PCI interruption occurs. 


IOBSIOCC (1 byte) 
in bits 0 and 1, the instruction-length code; in bits 2 and 3, the start 
subchannel (SSCH) condition code for the instruction the system issues to 
start the channel program; and, in bits 4 through 7, the program mask. 


IOBSTART (3 bytes) 
the starting address of the channel program to be executed. 


Reserved (1 byte) 
used only by the system. 


IOBDCBPT (3 bytes) 
the address of the data control block of the data set to be read or written by 
the channel program. 


IOBRESTR (1 byte) 
used by the system for volume repositioning in error recovery procedures. 


IOBRESTR+1 (3 bytes) 
if a related channel program is permanently in error, used by the system to 
chain together IOBs that represent dependent channel programs. To learn 
more about the conditions under which the chain is built, see “Interruption 
Handling and Error Recovery Procedures” on page 70. 


IOBINCAM (2 bytes) 
for magnetic tape, the amount by which the block count (DCBBLKCT) field 
in the device-dependent portion of the data control block is to be 
incremented. You may alter these bytes at any time. For forward 
operations, these bytes should contain a binary positive integer (usually +1); 
for backward operations, they should contain a binary negative integer. 
When these bytes are not used, all zeros must be specified. 


Reserved (2 bytes) 
used only by the system. 


IOBSEEK (first byte, M) 
for direct access devices, the extent entry in the data extent block that is 
associated with the channel program (0 indicates the first entry; 1 indicates 
the second, and so forth). For teleprocessing and graphic devices, it contains 
the UCB index. 


IOBSEEK (last 7 bytes, BBCCHHR) 
for direct access devices, the seek address for your channel program. 
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Event Control Block (ECB) Fields 


You must define an event control block (ECB) as a 4-byte area on a fullword 
boundary. When the channel program has been completed, the input/output 
supervisor places a completion code containing status information into the ECB 
(Figure 22 on page 93). Before examining this information, you must test for the 
setting of the “complete bit.” If the complete bit is not on, and your problem 
program cannot perform other useful operations, you should issue a WAIT macro 
instruction that specifies the event control block. Under no circumstances should 
you construct a program loop that tests for the complete bit. 


Data Extent Block (DEB) Fields 


The data extent block (DEB) is constructed by the system when an OPEN macro 
instruction is issued for the data control block. You may not modify the fields of 
the DEB, but you may examine them. 


Executing Fixed Channel Programs in Real Storage (EXCPVR) 


The EXCPVR macro instruction provides you with the same functions as the 
EXCP macro instruction (that is, a device-dependent means of performing 
input/output operations). In addition, it allows your program to improve the 
efficiency of the I/O operations in a paging environment by translating its own 
virtual channel programs to real channel programs. Authorized programs are 
allowed to execute in a V=V area and provide the EXCP processor with real 
channel programs. This eliminates the translation of channel programs by the 
EXCP processor. The program issuing the EXCPVR must remain in authorized 
state until the completion of the channel programs. 


Problem programs are authorized to use the EXCPVR macro instruction under the 
authorized program facility (APF). A description of how to authorize a program 
can be found in Supervisor Services and Macro Instructions. | 


EXCPVR 


iob-addr—A -type address, (2-12), or (1) 
the address of the input/output block of the channel program to be 
executed. 


To use EXCPVR, you must do all the things you would do to execute an EXCP 
request; in addition you must: 


1. Code PGFX=YES in the DCB associated with the EXCPVR requests and 
provide a page-fix (PGFX) appendage by specifying SIOA=symbol in the 
DCB. 


2. Fix the data area that contains your channel program, the data areas that are 
referred to by your channel program, your PCI appendage (if your program 
can generate program-controlled interrupts), and any area referred to by your 
PCI appendage. To cause EXCP to fix these data areas, you build a list that 
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WAIT bit=0 COMPLETE bit=1 Remainder of completion code 





bit 

0 1 2 31 

Wait bit 
A one bit in this position indicates that the WAIT macro instruction has been 
issued, but the channel program has not been completed. 

Complete bit 
A one bit in this position indicates that the channel program has been completed; 
if it has not been completed, a zero bit is in this position. 

Completion code 
This code, which includes the wait and complete bits, may be one of the following 
4--byte hexadecimal expressions: 
CODE MEANING 
7FOOO0000 The channel program has terminated without error. 
41000000 The channel program has terminated with a permanent error. 


42000000 The channel program has terminated because a direct access extent address 
has been violated. 


44000000 The channel program has been intercepted because of a permanent error 
associated with a device end for the previous request. You may 
reissue the EXCP macro instruction to restart the channel 
program. 


48000000 The request queue element for a channel program has been made available 
after it has been purged. 


4B000000 One of the following errors occurred during error recovery processing for 
a tape device. 


e The CSW command address in the IOB is zeros. 
e An unexpected load point was encountered. 


4FOOO0O00O0 Error recovery routines have been entered because of direct access error 
but are unable to read the home address or record 0. 


Figure 22. Event Control Block (ECB) after Posting of Completion Code (EXCP) 





contains the addresses of these virtual areas. You should build the list in your 
PGFX appendage. 


3. Determine whether the data areas in virtual storage specified in the address 
fields of your CCWs cross page boundaries. If they do, you must build an 
indirect data address list (IDAL) and put the address of the IDAL in the 
affected CCW. 


4. Translate the addresses in your CCWs from virtual to real addresses. 


All other areas related to the EXCP/EXCPVR I/O operation (that is, CC Ws, 
IDAWs, IOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
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addressable. Note, however, that the EXCP processor will allow both 24-bit and 


- 31-bit virtual I/O buffers to be fixed above 16 megabytes real. 


Items 3 and 4 must be done in your start-I/O (SIO) appendage. A description of 
the SIO appendage is presented under “‘Appendages”’ on page 71. 


Building the List of Data Areas to Be Fixed 


The EXCP processor expects programs using the EXCPVR macro instruction to 
pass a list of data areas to be fixed. This list is to be built in the PGFX appendage, 
as described below. 


The data areas you must fix in real storage (if not already fixed in real storage) are: 


1. The channel program. If the channel program is already in a fixed subpool, it 
does not have to be fixed. 


2. The data areas to which your channel program will write and from which your 
channel program will read. If the data areas are already in a fixed subpool, they 
do not have to be fixed. 


3. The PCI appendage, if used, and any areas accessed by the PCI appendage 
(DEB, IOB, and so forth). | 


EXCPVR users can specify 31-bit real data areas by creating CCWs through the 
use of IDAWs. : 


Page Fix (PGFX) and Start-I/O (SIO) Appendage 


Page-Fix List Processing 


This appendage consists essentially of two independent appendages. The complete 
appendage can be viewed as a re-enterable subroutine having two entry points, one 
for the SIO appendage and one for the PGFX appendage. 


The SIO entry point is located at offset 0 in the subroutine; any other location in 
the appendage may be branched to from this entry point. The entry point of the 

PGFX appendage is at offset +4 in the SIO subroutine, which is set in register 15 
as the entry point of the PGFX appendage. 


Page Fix (PGFX) Appendage: The purpose of this appendage is to list all the areas 
that must be fixed to prevent paging exceptions during the execution of the current 
I/O request. This appendage may be entered more than once. However, each time 
it is entered, it must create the same list of areas to be fixed. The appendage may 
use the 16-word save area pointed to by register 13. Registers 10, 11, and 13 may 
be used as work registers. 


Each page-fix entry placed in the list by the appendage must have the following 
doubleword format: 
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[O}1 31132] 33 63| 


Starting virtual 
address of area 
to be fixed 








Ending virtual 
address of area 
to be fixed + 1] 





On return from your PGFX appendage to the EXCP processor (via the return 
address provided in register 14), register 10 must point to the first page-fix entry 
and register 11 must contain the number of page-fix entries in the work area. The 
EXCP processor then fixes the pages corresponding to the areas listed by the 
PGFX appendage. The pages remain fixed until the associated I/O request 
terminates. 


If either the channel end appendage or the abnormal end appendage returns via the 
return address in register 14 plus 8, the PGFX appendage is not normally 
reentered. Instead, the SIO appendage is entered, and the page-fix list built by the 
PGFX appendage is still active. However, the PGFX appendage is entered after 
either the channel end appendage or the abnormal end appendage returns via the 
return address in register 14 plus 8 when a PURGE macro has been issued (for 
instance, when a storage swap has occurred). In this case, when I/O is restored, 
the PGFX appendage is entered. 








Note: The page-fix list must be in page-fixed storage. 





SIO Appendage: If you are using EXCPVR to execute your channel program, you 
must translate the virtual addresses in the operands of your channel program to real 
addresses. This should be done in your SIO appendage. If indirect data addressing 
is required, the SIO appendage should also build the indirect data address lists 
(IDALs) and turn on the IDA indicators in the associated CCWs. 


Translating Virtual Addresses and Building the IDAL: You must convert the virtual 
addresses in the channel program to real addresses. You must also check the areas 
whose addresses appear in bits 8 through 31 of your CCWs to determine whether 
the data areas cross 2K-byte boundaries. If they do, you must provide an entry in 
the IDAL for each 2K-byte boundary crossed. The channel subsystem uses the 
IDAL to identify the address where it will continue reading or writing when a 
2K-byte boundary is crossed during a read or write operation. The IDAL must 
contain real addresses when it is processed by the channel. 


In MVS/XA, the LRA instruction returns a 31-bit real address regardless of the 
addressing mode. You must be careful when you construct the IDAW to ensure 
that the real storage obtained by GETMAIN (or branch entry) is below 16 
megabytes. Do your page fixing before you issue the LRA. (See Supervisor 
Services and Macro Instructions or System Macros and Facilities for information on 
how to obtain real storage below 16 megabytes real.) 
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- 
31 32 39 40 
I DAL 
First Indirect Data 
Address Word 
Second Indirect Data 
Address Word 
Subsequent Indirect 
Data Address Word 
Notes: 
I. You must put one entry in the IDAL for each 2K-byte page boundary your data 
area Crosses. 
2. If the CCW has an IDAL address rather than a data address, bit 37 must be set 
to signal this to the channel. Hs 
3. The maximum number of entries needed in the IDAL is determined from the eed 


count in the CCW as follows: 


Number of IDAL entries=((CCW byte-count — 1)/2048) + 1. 
(Round up division to next highest integer if remainder is not zero.) 


The number of IDAL entries required ultimately depends on the number of 
2K-byte boundaries crossed by the data. For example, if your data is 800 bytes 
long and does not cross a 2K-byte page boundary, no IDAL entries are required. 
If your data crosses a 4K-byte page boundary, then two IDAL entries are required. 
If your data is 5000 bytes long, at least two IDAL entries are required. If your 
data crosses two 4K-byte page boundaries, four IDAL entries are required. 


The first indirect address is the real address of the first byte of the data area. The 
second and subsequent indirect addresses are the real addresses of the second and 
subsequent 2K-byte boundaries of the data area. 
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For example, if the data area real address is X'707FF' and the byte count is 
X'1802', the IDAL would contain the following real addresses (assuming the real 
addresses are contiguous, which may not always be the case): 





7O7FF 
70800 
71000 


If the data area real address is X'707FF' and the byte count is X'800', the IDAL 
would contain the following addresses: 


7O7FF 
70800 
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Chapter 3. Reading from and Writing to Direct Access Devices (XDAP) 


Execute direct access program (XDAP) is a macro instruction that you may use to 
read, verify, or update a block on a direct access volume. This chapter explains 
what the XDAP macro instruction does and how you can use it. The control block 
generated when XDAP is issued and the macro instructions used with XDAP are 
also discussed. 


Because most of the specifications for XDAP are similar to those for the execute 
channel program (EXCP) macro instruction, you should be familiar with the 
“Executing Your Own Channel Programs (EXCP)”’ chapter of this publication, 
and with the information contained in Data Administration Guide that provides 
how-to information for using the access method routines of the system control 
program. 


If you are not using the standard IBM data access methods, you can, by issuing 
XDAP, generate the control information and channel program necessary for 
oes reading or updating the records of a data set. (However, XDAP cannot be used to 
( | read, verify, or update a SYSIN or SYSOUT data set.) 


You cannot use XDAP to add blocks to a data set, but you can use it to change the 
keys of existing blocks. Any block configuration and any data set organization can 
be read or updated. 


Although the use of XDAP requires less storage than do the standard access 
methods, it does not provide many of the control program services that are included 
in the access methods. For example, when XDAP is issued, the system does not 
block or unblock records and does not verify block length. 


To issue XDAP, you must provide the actual track address of the track containing 
the block to be processed. You must also provide either the block identification or 
the key of the block, and specify which of these is to be used to locate the block. If 
a block is located by identification, both the key and data portions of the block 
may be read or updated. If a block is located by key, only the data portion can be 
processed. 


For additional control over I/O operations, you may write appendages that must be 
entered into the LPA library. Descriptions of these routines and their coding 
specifications are included under Chapter 2, ‘Executing Your Own Channel 
Programs (EXCP)” on page 63. 
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XDAP Requirements 


When using the XDAP macro instruction, you must, somewhere in your program, 
code a DCB macro instruction that produces a data control block (DCB) for the 
data set to be read or updated. You must also code an OPEN macro instruction 
that initializes the data control block and produces a data extent block (DEB). The 
OPEN macro instruction must be executed before any XDAP macro instructions 
are executed. | 


When the XDAP macro instruction is assembled, a control block and executable 
code are generated. This control block may be logically divided into three sections: 


e Anevent control block (ECB) that is supplied with a completion code each 
time the direct access channel program is terminated. 


e An input/output block (IOB) that contains information about the direct access 
channel program. 


e A direct access channel program that consists of three or four channel 
command words (CCWs). The type of channel program generated depends on 
specifications in the parameters of the XDAP macro instruction. When 
executed, it locates a block by either its actual address or its key and reads, 
updates, or verifies the block. 


When the channel program has terminated, a completion code is placed into the 
event control block. After issuing XDAP, you should therefore issue a WAIT 
macro instruction, specifying the address of the event control block, to regain 
control when the direct access program has terminated. If volume switching is 
necessary, you must issue an EOV macro instruction. When processing of the data 
set has been completed, you must issue a CLOSE macro instruction to restore the 
data control block. 


Macro Specifications for Use with XDAP 


When you are using the XDAP macro instruction, you must also code DCB, 
OPEN, CLOSE, WAIT, and, in some cases, the EOV macro instructions. The 
parameters of the XDAP macro instruction are listed and described here. For the 
other required macro instructions, special requirements or options are explained, 
but you should see ‘“‘Macro Specifications for Use with EXCP” on page 73 for 
listings of their parameters. 


Defining a Data Control Block (DCB) 


You must issue a DCB macro instruction for each data set to be read, updated, or 
verified by the direct access channel program. To learn which macro instruction 
parameters to code, see ‘“‘Defining Data Control Blocks for EXCP (DCB)” on 
page 73. 
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Initializing a Data Control Block (OPEN) 





The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. You must issue OPEN for all data 
control blocks that are to be used by the direct access program. Some of the 
procedures performed when OPEN is executed are: 


e Construction of data extent block (DEB) 


e Transfer of information from DD statements and data set labels to the data 
control block 


e Verification or creation of standard labels 
e Loading of programmer-written appendage routines 


The two parameters of the OPEN macro instruction are the address(es) of the data 
control block(s) to be initialized and the intended method of I/O processing of the 
data set. The method of processing may be specified as INPUT, OUTPUT, or 

| EXTEND; however, if nothing is specified, INPUT is assumed. The parameters 

| and different forms of the OPEN macro instruction are described in Data 

| Administration: Macro Instruction Reference. 


Executing Direct Access Programs (XDAP) 


7 The XDAP macro instruction produces the XDAP control block (that is, the ECB, 
( : IOB, and channel program) and executes the direct access channel program. The 
) format of the XDAP macro instruction is: 


[symbol] ecb-symbol 
slype 
,adcb-addr 
yarea-addr 


ylength-value 

[(key-addr, keylength-value)| 
»blkref-addr 

ylsector-addr| 





ecb-symbol—symbol or (2-12) 
the symbolic name to be assigned to the XDAP event control block. 
Registers can be used only with MF=E. 


type—{RI | RK | WI | WK | VI| VK} 
the type of I/O operation intended for the data set and the meno" by which 
blocks of the data set are to be located. One of the combinations shown 
must be coded in this field. 


The codes and their meanings are: 


R Read a block. 
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WwW Update a block. 


V Verify that the device is able to read the contents of a block, 
but do not transfer data. 


I Locate a block by identification. (The key portion, if present, 
and the data portion of the block are read, updated, or verified.) 


K Locate a block by key. (Only the data portion of the block is 
read, updated, or verified.) If you code this value, you must 
code the 'key-addr,keylength-value' operands. 


dcb-addr—A -type address or (2-12) 
the address of the data control block for the data set. If this data control 
block is also being used by a sequential access method (BSAM, BPAM, 
QSAM), you must reassemble the XDAP macro instruction. Otherwise, 
sequential access method appendages will be called at the conclusion of the 
XDAP channel program. 


area-addr—A-type address or (2-12) 
the address of an input or output area for a block of the data set. 


length-value—absexp or (2-12) 
the number of bytes to be transferred to or from the input or output area. If 
blocks are to be located by identification and the data set contains keys, the 
value must include the length of the key. The maximum number of bytes 
transferred is 32767. 


key-addr—R.X-type address or (2-12) 
when blocks are to be located by key, the address of a virtual storage field 
that contains the key of the block to be read, updated, or verified. 


keylength-value—absexp or (2-12) 
when blocks are to be located by key, the length of the key. The maximum 
length is 255 bytes. 


blkref-addr—RX-type address or (2-12) 
the address of a field in virtual storage containing the actual track address of 
the track containing the block to be located. The actual address of a block is 
in the form MBBCCHHR, where M indicates which extent entry in the data 
extent block is associated with the direct access program; BB is not used, but 
must be zero; CC indicates the cylinder address; HH indicates the actual 
track address; and R indicates the block identification. R is not used when 
blocks are to be located by key. (For more detailed information, see 
“Converting a Relative Track Address to an Actual Track Address” on 
page 106.) 


sector-addr—RX-type address or (2-12) 
the address of a 1-byte field containing a sector value. The sector-address 
parameter is used for rotational position sensing (RPS) devices only. The 
parameter is optional, but its use will improve channel performance. When 
the parameter is coded, a set-sector CCW (using the sector value indicated 
by the data address field) precedes the search-ID-equal command in the 
channel program. The sector-address parameter is ignored if the type 
parameter is coded as RK, WK, or VK. If a sector address is specified in the 
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execute form of the macro, then a sector address, not necessarily the same, 
a must be specified in the list form. The sector address in the executable form 
| will be used. 


Note: No validity check is made on either the address or the sector value 
when the XDAP macro is issued. However, a unit check/command reject 
interruption will occur during channel-program execution if the sector value 
is invalid for the device or if the sector-addr operand is used when accessing 
a device without RPS. (For more detailed information, see “Obtaining 
Sector Number of a Block on a Device with the RPS Feature’ on page 108.) 


MF= 
you may use the L-form of the XDAP macro instruction for a macro 
expansion consisting of only a parameter list, or the E-form for a macro 
expansion consisting of only executable instructions. 





MF=E 
The first operand (ecb-symbol) is required and may be coded as a symbol or 
supplied in registers 2 through 12. The type, dcb-addr, area-addr, and 
length-value operands may be supplied in either the L- or E-form. The 
blkref-addr operand may be supplied in the E-form or moved into the 
IOBSEEK field of the IOB by you. The sector-addr is optional; it may be 
coded either in both the L- and E-form or in neither. 


MF=L 
The first two operands (ecb-symbol and type) are required and must be 
coded as symbols. If you choose to code length-value or keylength-value, 
they must be absolute expressions. Other operands, if coded, must be 
A-type addresses. (blkref-addr is ignored if coded.) 





Note: The XDAP macro builds a channel program containing A-type addresses. 
These addresses refer to storage within the L-form of the macro. If you copy the 
L-form of the macro to a workarea so that the program may be reentrant, the 
E-form of the XDAP macro does not update the A-type addresses. This results in 
an invalid channel program. 


The dcb-addr, area-addr, blkref-addr, and sector-value operands may be coded as 
RX-type addresses or supplied in registers 2 through 12. The length-value and 
keylength-value operands can be specified as absolute expressions or decimal 
integers or supplied in registers 2 through 12. 
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End of Volume (EOV) 


The EOV macro instruction identifies end-of-volume and end-of-data-set Seay 
conditions. For an end-of-volume condition, EOV causes switching of volumes 
and verification or creation of standard labels. For an end-of-data-set condition, 
EOV causes your end-of-data-set routine to be entered. When using XDAP, you 
issue EOV if switching of direct access volumes is necessary or if secondary 
allocation is to be performed for a direct access data set opened for output. 


For details about the parameters of the EOV macro instruction, see “End of 
Volume (EOV)” on page 81. 


Restoring a Data Control Block (CLOSE) 


The CLOSE macro instruction restores one or more data control blocks so that 
processing of their associated data sets can be terminated. You must issue CLOSE 
for all data sets that were used by the direct access channel program. Some of the 
procedures performed when CLOSE is executed are: 


e Release of data extent block (DEB) 


¢« Removal of information transferred to data control block fields when OPEN 
was executed 


e Verification or creation of standard labels 

e Release of programmer-written appendage routines 

The CLOSE macro instruction must identify the address of at least one data 
control block to be restored, and may specify other parameters. The parameters 


and different forms of the CLOSE macro instruction are described in Data 
Administration: Macro Instruction Reference. 


Control Blocks Used with XDAP 


The three control blocks generated during execution of the XDAP macro 
instruction are described here. 


Event Control Block (ECB) 


The event control block (ECB) begins on a fullword boundary and occupies the 
first 4 bytes of the XDAP control block. Each time the direct access channel 
program terminates, the I/O supervisor places a completion code containing status 
information into the event control block (Figure 23 on page 105). Before 
examining this information, you must wait for the completion of the channel 
program by issuing a WAIT macro instruction that specifies the address of the 
event control block. 


104 MVS/XA System—Data Administration 














Input/Output Block (IOB) 


The input/output block (IOB) is 40 bytes in length and immediately follows the 
event control block. “Control Block Fields’ on page 88 contains a diagram of the 
input/output block (Figure 23 on page 105). You may want to examine the 
IOBSENSO, IOBSENS1, and IOBCSW fields if the ECB is posted with X'41'. 





WAIT bit COMPLETE bit Completion code 
bit 
0 1 2 31 
Wait bit 
A one bit in this position indicates that the direct access channel program has not 
been completed. 
Complete bit 


A one bit in this position indicates that the channel program has been completed; 
if it has not been completed, a zero bit is in this position. 


Completion code 
This code, including the wait and complete bits, may be one of the following 4—byte 
hexadecimal expressions: 
CODE MEAN I NG 
7F000000 Direct access program has terminated without error. 


41000000 Direct access program has terminated with permanent error. 


42000000 Direct access program has terminated because a direct access extent 
address has been violated. 


4FO00000 Error recovery routines have been entered because of direct access error 
but are unable to read home address or record 0. 


Figure 23. Event Control Block (ECB) after Posting of Completion Code (XDAP) 


Direct Access Channel Program 


The direct access channel program is 24 bytes in length (except when set sector is 


used for RPS devices) and immediately follows the input/output block. Depending 


on the type of I/O operation specified in the XDAP macro instruction, one of four 
channel programs may be generated. The three channel command words for each 
of the four possible channel programs are shown in Figure 24 on page 106. 


When a sector address is specified with an RI, VI, or WI operation, the channel 


program is 32 bytes in length. Each of these channel programs in Figure 24 on 
page 106 would be, in this case, preceded by a set sector command. 
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Converting a Relative Track Address to an Actual Track Address 


To issue XDAP, you must provide the actual track address of the track containing 


the block to be processed. If you know only the relative track address, you can 


convert it to the actual address by using a resident system routine. The entry point 


to this conversion routine is labeled IECPCNVT. The address of the entry point 
(CVTPCNVT) is in the communication vector table (CVT). The address of the 
CVT is in location 16. 


Type of I/O Operation CCW Command Code 
Read by identification 1 Search ID Equal 
2 Transfer in Channel 
Verify by identification! 3 Read Key and Data 
Read by key 1 Search Key Equal 
2 Transfer in Channel 
Verify by key| 3 Read Data 
Write by identification 1 Search ID Equal 
2 Transfer in Channel 
3 Write Key and Data 
Write by key 1 Search Key Equal 
Transfer in Channel 
3 Write Data 


1 For verifying operations, the third CCW is flagged to 


suppress the transfer of information to virtual storage. 


Figure 24. The XDAP Channel Programs 


The conversion routine does all its work in general registers. You must load 


registers 0, 1, 2, 14, and 15 with input to the routine. Register usage is as follows: 


Register Use 


0 Must be loaded with a 4-byte value of the form TTRN, where TT is 


the track number relative to the beginning of the data set, R is the the 
block identification on that track, and N is the concatenation number 


of a BPAM data set. (0 indicates the first data set in the 


concatenation, an nonconcatenated BPAM data set, or a non-BPAM 


data set.) 

1 Must be loaded with the address of the data extent block (DEB) of the 
data set. 

2 Must be loaded with the address of an 8-byte area that is to receive 


the actual address of the block to be processed. The converted 


address is of the form MBBCCHHR, where M indicates which extent 


entry in the data extent block is associated with the direct access 
program (0 indicates the first extent, 1 indicates the second, and so 


forth); BB is two bytes of zeros; CC is the cylinder address; HH is the 


actual track address; and R is the block number. 
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3-8 Are not used by the conversion routine. 





9-13 Are used by the conversion routine and are not restored. 


14 Must be loaded with the address to which control is to be returned 
after execution of the conversion routine. 





15 Is used by the conversion routine as a base register and must be loaded 
with the address where the conversion routine is to receive control. 


Return Codes from the Conversion Routine 


When control is returned to your program, register 15 will contain one of the 
following return codes: 


Code Meaning 
O(X'00') Successful conversion. 


4(X'04') The relative block address converts to an actual track address outside 
the extents defined in the DEB. 


( Converting an Actual Track Address to a Relative Track Address 


To get the relative track address when you know the actual track address, you can 
use the conversion routine labeled IECPRLTV. The address of the entry point 
(CVTPRLTV) is in the communication vector table (CVT). The address of the 
CVT is in location 16. 


The conversion routine does all its work in general registers. You must load 
registers 1, 2, 14, and 15 with input to the routine. Register usage is as follows: 


Register Use 

0 Will be loaded with the resulting TTRO to be passed back to the caller. 

1 Must be loaded with the address of the data extent block (DEB) of the 
data set. 

2 Must be loaded with the address of an 8-byte area containing the 
actual address to be converted to a TTR. The actual address is of the 
form MBBCCHHR. 

3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not restored. 
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14 Must be loaded with the address to which control is to be returned 
after execution of the conversion routine. 


15 Is used by the conversion routine as a base register and must be loaded 
| with the address where the conversion routine is to receive control. 


Obtaining Sector Number of a Block on a Device with the RPS Feature 


To obtain the performance improvement given by rotational position sensing, you 
should specify the sector-addr parameter in the XDAP macro. For programs that 
can be used with both RPS and non-RPS devices, the UCBRPS bit (bit 3 at an 
offset of 17 bytes into the UCB) should be tested to determine whether the device 
has rotational position sensing. If the UCBRPS bit is off, a channel program with a 
“‘set sector’? command must not be issued to the device. 


The sector-addr parameter on the XDAP macro specifies the address of a 1-byte 
field in your region. You must store the sector number of the block to be located 
in this field. You can obtain the sector number of the block by using a resident 
conversion routine, IECOSCR1. The address of this routine is in field CVTOSCR1 
of the CVT, and the address of the CVT is in location 16. The routine should be 
invoked via a BALR 14,15 instruction. If you are passing the track balance to the 
routine, invoke the routine using a BAL 14,8(15). If you are computing the sector 
value on modulo devices (3375 and 3380) with variable length records, you must 
pass the track balance to the sector convert routine. 


For RPS devices, the conversion routine does all its work in general registers. You 
must load registers 0, 2, 14, and 15 with input to the routine. Register usage is as 
follows: 
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Register Use 


0 For fixed, standard blocks or fixed, unblocked records not in a 
partitioned data set: Register 0 must be loaded with a 4-byte value in 
the form XXKR, where XX is a 2-byte field containing the physical 
block size, K is a 1-byte field containing the key length, and R is a 
1-byte field containing the number of the record for which a sector 
value is desired. The high-order bit of register 0 must be turned off 
(set to 0) to indicate fixed-length records. 





Passing the track balance: Register 0 must be loaded with the 4-byte 
value of the track balance of the record preceding the required record. 


For all other cases: Register 0 must be loaded with a 4-byte value in 
the form BBIR, where BB is the total number of key and data bytes on 
the track up to, but not including, the target record; I is a 1-byte key 
indicator (1 for keyed records, 0 for records without keys); and R isa 
1-byte field containing the number of the record for which a sector 
value is desired. The high-order bit of register 0 must be turned on 
(set to 1) to indicate variable-length records. 


1 Not used by the sector-convert routine. 

2 Must be loaded with a 4-byte field where the first byte is the UCB 
a device type code for the device (obtainable from UCB+19), and the 

( . remaining three bytes are the address of a 1-byte area that is to 

. receive the sector value. 

3-8 Not used. 

9-11 Used by the convert routine and are not saved or restored. 

12,13 Not used. 

14 Must be loaded with the address in which control is to be returned 


after execution of the sector conversion routine. 


15 Used by the conversion routine as a base register and must be loaded 
with the address of the entry point to the conversion routine. 
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Chapter 4. Password Protecting Data Sets 


The password protection described in this chapter does not apply to VSAM data 
sets. Information about VSAM data set protection is in VSAM Administration: 
Macro Instruction Reference and Access Method Services Reference. (For 
information on RACF and its relationship to password protection, see RACF 
General Information.) To use the data set protection feature of the operating 
system, you must create and maintain a PASSWORD data set consisting of records 
that associate the names of the protected data sets with the password assigned to 
each data set. There are four ways to maintain the PASSWORD data set: 


e You can write your own routines. 

e You can use the PROTECT macro instruction. 

e You can use the utility control statements of the IEHPROGM utility program. 
e If you have TSO, you can use the TSO PROTECT command. 

This chapter discusses only the first two of the four ways: It provides technical 
detail about the PASSWORD data set that is necessary for writing your own 
routines, and it describes how to use the PROTECT macro instruction. (The last 
two of the four ways are discussed in other publications, as indicated in the list of 
publications below.) 

Before using the information in this chapter, you should be familiar with 
information in several related publications. The following publications are 


recommended: 


e Data Administration Guide contains a general description of the data set 
protection feature. 


e System Messages contains a description of the operator messages and replies 
associated with the data set protection feature. 


e JCL Reference contains a description of the data definition (DD) statement 
parameter used to indicate that a data set is to be password protected. 


¢ Utilities contains a description of how to maintain the PASSWORD data set 
using the utility control statements of the IEHPROGM utility program. 


e TSO Command Language Reference describes the use of the TSO PROTECT 
command. 
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Providing Data Set Security 


In addition to the usual label protection that prevents the opening of a data set 
without the correct data set name, the operating system provides data set security 
options that prevent unauthorized access to confidential data. Password protection 
prevents access to data sets until a correct password is entered by the system 
operator, or, for TSO, by a remote terminal operator. | 


The following are the types of access allowed to password-protected data sets: 
¢ PWREAD/PWWRITE—A password is required for read or write. 


e PWREAD/NOWRITE—A password is required for read. Writing is not 
allowed. 


¢« NOPWREAD/PWWRITE—Reading is allowed without a password. A 
password is required to write. 


To prepare for use of the data set protection feature of the operating system, you 
place a sequential data set, named PASSWORD, on the system residence volume. 
This data set must contain at least one record for each data set placed under 
protection. In turn, each record contains a data set name, a password for that data 
set, a counter field, a protection mode indicator, and a field for recording any 
information you desire to log. On the system residence volume, these records are 
formatted as a “‘key area” (data set name and password) and a “data area’”’ 
(counter field, protection mode indicator, and logging field). The data set is 
searched on the “‘key area.” 


Note: The area allocated to the data set should not have been previously used for 
a PASSWORD data set, as this may cause unpredictable results when adding 
records to the data set. 


You can write routines to create and maintain the PASSWORD data set. If you 
use the PROTECT macro instruction to maintain the PASSWORD data set, see 
‘Maintaining the PASSWORD Data Set (PROTECT Macro)” on page 116. If 
you use the IEHPROGM utility program to maintain the PASSWORD data set, see 
Utilities. These routines may be placed in your own library or in the system’s 
library (SYS1.LINKLIB). You may use a data management access method or 
EXCP programming to read from and write to the PASSWORD data set. 


If a data set is to be placed under protection, it must have a protection indicator set 
in its label (format-1 DSCB or header 1 tape label). This is done by the operating 
system when the data set is created, by the IEHPROGM utility program, or by the 
PROTECT macro when creating or adding the control password. The protection 
indicator is set in response to a value in the LABEL= operand of the DD statement 
associated with the data set being placed under protection. JCL Reference describes 
the LABEL operand. 


Note: Data sets on magnetic tape are protected only when standard labels are 
used. 


Password-protected data sets can only be accessed by programs that can supply the 
correct password. When the operating system receives a request to open a 
protected data set, it first checks to see whether the data set has already been 
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opened for this job step. If so, only the access mode will be checked to determine 

_ whether it is compatible with the protection mode under which it was previously 

- opened. If the data set has not been previously opened by this job step or if the 
access mode is not compatible with the protection mode under which it was 
previously opened, a message is issued that asks for the password; the message 
goes to the operator console. If the program requesting that the data set be opened 
is running under TSO in the foreground, the message goes to the TSO terminal 
operator. If you want the password supplied by another method in your 
installation, you can modify the READPSWD source module or code a new routine 
to replace READPSWD in SYS1.LPALIB. 





PASSWORD Data Set Characteristics 


The PASSWORD data set must reside on the same volume as your operating 
system. The space you allocate to the PASSWORD data set must be contiguous, 
that is, its DSCB must indicate only one extent. The amount of space you allocate 
depends on the number of data sets your installation wants to protect. Each entry 
in the PASSWORD data set requires 132 bytes of space. The organization of the 
PASSWORD data set is physical-sequential; the record format is unblocked, 
fixed-length records (RECFM=F). Each record that forms the data area is 80 
bytes long (LRECL=80,BLKSIZE=80) and is preceded by a 52-byte key 
(KEYLEN=52). The key area contains the fully qualified data set name of as 
many as 44 bytes and a password of one to eight bytes, left justified with blanks 
added to fill the areas. The password assigned may be from one to eight 
alphameric characters in length. 


( | Note: For data sets on magnetic tape designed according to the specifications of 
the International Organization for Standardization (ISO) 1001-1979, the 
equivalent American National Standards Institute (ANSI) X3.27-1978, or the 
Federal Information Processing Standards (FIPS) 79, do not include generation 
and version numbers as part of generation data set names. The generation and 
version numbers are not included as part of the names in the tape labels and are 
ignored if included in the PASSWORD data set. 


You can protect the PASSWORD data set itself by creating a password record for 
it when your program initially builds the data set. Thereafter, the PASSWORD 
data set cannot be opened (except by the operating system routines that scan the 
data set) unless the operator enters the password. 


Note: If a problem occurs on a password-protected system data set, maintenance 
personnel must be provided with the password in order to access the data set and 
resolve the problem. 


Creating Protected Data Sets 


A data definition (DD) statement parameter (LABEL=) may be used to indicate 
that a data set is to be password protected. For data sets on DASD, an alternative 
method is to use the PROTECT macro instruction for a previously allocated data 
set. A data set may be created and the protection indicator set in its label without 
entering a password record for it in the PASSWORD data set. 





Operating procedures at your installation must ensure that password records for all 
data sets currently password-protected are entered in the PASSWORD data set. 
Installations where independent computing systems share common DASD 
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resources must ensure that PASSWORD data sets on all systems contain the. 
appropriate password records for any protected data set on shared DASD. 


Under certain circumstances, the order in which data sets are allocated and 
unallocated from multiple systems on shared DASD may result in loss of password 
protection. For example, if an unprotected data set is allocated and opened by a 
user on System A and then scratched by a different user on System B, the first user 
is given a ‘“‘window’’ to the unallocated (free) area. If any data set, protected or 
unprotected, is allocated in that space by a user on either system during the time 
the “window” is open, the new data set has no protection from the user with the 
‘““window.”’ 


While the allocation disposition is still NEW, a password-protected data set can be 
used without supplying a password. However, once the data set is unallocated, any 
subsequent attempt to open will result in termination of the program unless the 
password record is available and the correct password is supplied. Note that, if the 
protection mode is NOPWREAD and the request is to open the data set for input 
or read backward, no password will be required. 


Tape Volumes Containing More Than One Password-Protected Data Set 


To password protect a data set on a tape volume containing other data sets, you 
must password protect all the data sets on the volume. (Standard labels—SL, SUL, 
AL, or AUL—are required. For definitions of these label types and the 
protection-mode indicators that can be used, see Magnetic Tape Labels and File 
Structure Administration.) 


If you issue an OPEN macro instruction to create a data set following an existing, 
password-protected data set, the password of the existing data set will be verified 
during open processing for the new data set. The password supplied must be 
associated with a PWWRITE protection-mode indicator. 


Protection Feature Operating Characteristics 


Termination of Processing 


The topics that follow provide information concerning actions of the protection 
feature in relation to termination of processing, volume switching, data set 
concatenation, SCRATCH and RENAME functions, and counter maintenance. 


Processing is terminated when: 


1. The operator cannot supply the correct password for the protected data set 
being opened after two tries. 


2. A password record does not exist in the PASSWORD data set for the protected 
data set being opened. 


3. The protection-mode indicator in the password record and the method of I/O 
processing specified in the Open routine do not agree, for example, OUTPUT 
specified against a read-only protection-mode indicator. 


4. There is a mismatch in data set names for a data set involved in a volume 
switching operation. This is discussed in the next paragraph. 
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Volume Switching 


The system ensures a continuation of password protection when volumes of a 
multivolume data set are switched. It accepts a newly-mounted tape volume to be 
used for input or a newly-mounted direct access volume, regardless of its use, if 
these conditions are met: 


e The data set name in the password record for the data set is the same as the 
data set name in the JFCB. (This ensures that the problem program has not 
changed the data set name in the JFCB since the data set was opened.) 


e The protection-mode indicator in the password record is compatible with the 
processing mode, and a valid password has been supplied. 


The system accepts a newly-mounted tape volume to be used for output under any 
of these conditions: 


e The security indicator in the HDR1 label indicates password protection; the 
data set name in the password record is the same as the data set name in the 
JFCB; and the protection-mode indicator is compatible with the processing 
mode. (If the data set name in the JFCB has been changed, a new password is 
requested from the operator.) 


s The security indicator in the HDR1 label does not indicate password 
protection. (A new label will be written with the security indicator indicating 
password protection.) 


e Only a volume label exists. (A HDR1 label will be written with the security 
indicator indicating password protection.) 


Data Set Concatenation 


A password is requested for every protected data set that is involved in a 
concatenation of data sets, regardless of whether the other data sets involved are 
protected or not. 


SCRATCH and RENAME Functions 


To delete or rename a protected data set, it is necessary that the job step making 
the request be able to supply the password. The system first checks to see if the 
job step is currently authorized to write to the data set. If not, message IEC301A 
is issued to request the password. The password provided must be associated with 
a “WRITE” protection-mode indicator. 


Counter Maintenance 
The operating system increments the counter in the password record on each usage, 
but no overflow indication will be given (overflow after 65535 openings). You 


must provide a counter maintenance routine to check and, if necessary, reset this 
counter. 
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Maintaining the PASSWORD Data Set (PROTECT Macro) 


To use the PROTECT macro instruction, your PASSWORD data set must be on 
the system residence volume. The PROTECT macro can be used to: 


e Add an entry to the PASSWORD data set. 

e Replace an entry in the PASSWORD data set. 

e Delete an entry from the PASSWORD data set. 

e Provide a list of information about an entry in the PASSWORD data set; this 
list will contain the security counter, access type, and the 77 bytes of security 
information in the “data area” of the entry. 

In addition, the PROTECT macro updates the DSCB of a protected direct access 


data set to reflect its protection status; this feature eliminates the need for you to 
use job control language when you protect a data set. 


PASSWORD Data Set Characteristics and Record Format (With PROTECT macro) 


When you use the PROTECT macro, the record format and characteristics of the 
PASSWORD data set are no different from the record format and characteristics 
that apply when you use your own routines to maintain it. 


Number of Records for Each Protected Data Set 


Protection-Mode Indicator 


Sees 


When you use the PROTECT macro, the PASSWORD data set must contain at 
least one record for each protected data set. The password (the last 8 bytes of the 
‘“‘key area”’) that you assign when you protect the data set for the first time is called 
the control password. In addition, you may create as many secondary records for 
the same protected data set as you need. The passwords assigned to these 
additional records are called secondary passwords. This feature is helpful if you 
want several users to have access to the same protected data set, but you also want 
to control the way they can use it. For example: One user could be assigned a 
password that allowed the data set to be read and written, and another user could 
be assigned a password that allowed the data set to be read only. 


Note: The PROTECT macro will update the protection-mode indicator in the 
format-1 DSCB in the protected data set only when you issue it for adding, 
replacing, or deleting a control password. 


You can set the protection-mode indicator (third data byte) in the password record 
to one of four different values: 


e X'Q0' to indicate that the password is a secondary password and the protected 
data set is to be read only (PWREAD). 


e X'80' to indicate that the password is the control password and the protected 
data set is to be read only (PWREAD). 


Tea 
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e X!'OQ1' to indicate that the password is a secondary password and the protected 
data set is to be read and written (PWREAD/PWWRITEB). 


e X'81' to indicate that the password is the control password and the protected 
data set is to be read and written (PWREAD/PWWRITE). 


Because of the sequence in which the protection status of a data set is checked, the 
following defaults will occur: 


If control password is: Secondary password must be: 

1.  PWREAD/PWWRITE or PWREAD/PWWRITE or 
PWREAD/NOWRITE PWREAD/NOWRITE 

2. NOPWREAD/PWWRITE NOPWREAD/PWWRITE 


If the control password is set to either of the settings in item 1 above, the 
secondary password will be set to PWREAD/PWWRITE if you try to set it to 
NOPWREAD/PWWRITE. 


If the control password is changed from either of the settings in item 1 to the 
setting in item 2 above, the secondary password will be automatically reset to 
NOPWREAD/PWWRITE. 


If the control password is changed from the setting in item 2 to either of the 
Settings in item 1 above, the secondary password is set by the system to 
PWREAD/PWWRITE. 


Because the DSCB of the protected data set is updated only when the control 
password is changed, you may request protection attributes for secondary 
passwords that conflict with the protection attributes of the control password. 


PROTECT Macro Syntax 


The format is: 


[symbol] PROTECT | parameter list address 


parameter list address—A-type address, (2-12), or (1) 
indicates the location of the parameter list. The parameter list must be set up 
before the PROTECT macro is issued. The address of the parameter list 
may be passed in register 1, in any of registers 2 through 12, or as an A-type 
address. The first byte of the parameter list must be used to identify the 
function (add, replace, delete, or list) you want to perform. See Figure 25 
on page 118 through Figure 28 on page 123 for the parameter lists and 
codes used to identify the functions. 


Note: The parameter lists and the areas addressed by the list must reside below 16 
megabytes virtual. 
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PROTECT Macro Parameter Lists 
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8 00 21 New password pointer 
9g 00 00 00 24 String length 


12 00 25 String pointer 
Notes: 
0 X'O1' 


Entry code indicating ADD function. 


4 Data set name length. 
5 Data set name pointer. 


13 Control password pointer. | 
The control password is the password assigned when the data set was placed under protection for the 
first time. The pointer can be 3 bytes of binary zeros if the new password is the control password. 


16 Number of volumes. | 
If the data set is not cataloged and you want to have it flagged as protected, you must specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, you provide the address of a 
list of volume serial numbers in this field. Zeros indicate that the catalog information should be used. 


20 Protection code. 
A one-byte number indicating the type of protection: X'00' indicates default protection (for the ADD 
function; the default protection is the type of protection specified in the control password record of the 
data set); X'O1' indicates that the data set is to be read and written; X'02' indicates that the data set is 
to be read only; and X'03' indicates that the data set can be read without a password, but a password is 
needed to write into it. The PROTECT macro will use the protection code value, specified in the 
parameter list, to set the protection-mode indicator in the password record. 


Figure 25 (Part 1 of 2). Parameter List for ADD Function 
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21 New password pointer. 
If the data set is being placed under protection for the first time, the new password becomes the control 
password. If you are adding a secondary entry, the new password is different from the control password. 


24 String length. 
The length of the character string (maximum 77 bytes) that you want to place in the optional 
information field of the password record. If you don’t want to add information, set this field to zero. 





25 String pointer. 
The address of the character string that is going to be put in the optional information field. If you don’t 
want to add additional information, set this field to zero. 


Figure 25 (Part 2 of 2). Parameter List for ADD Function 
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Notes: 








0 X'02'. 
Entry code indicating REPLACE function. 


4 Data set name length. 
5 Data set name pointer. 


9 Pointer to current password. 
The address of the password that is going to be replaced. 


13 Control password pointer. 
The address of the password assigned to the data set when it was first placed under protection. The 
pointer can be set to 3 bytes of binary zeros if the current password is the control password. 


16 Number of volumes. 
If the data set is not cataloged and you want to have it flagged as protected, you have to specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, you have to provide the 
address of a list of volume serial numbers in this field. If this field is zero, the catalog information will be 
used. 


20 Protection code. 
A one-byte number indicating the type of protection: X'0O' indicates that the protection is default 
protection (for the REPLACE function the default protection is the protection specified in the current 
password record of the data set); X'O1' indicates that the data set is to be read and written; X'02' 
indicates that the data set is to be read only; and X'03' indicates that the data set can be read without a 
password, but a password is needed to write into the data set. 


Figure 26 (Part 1 of 2). Parameter List for REPLACE Function 
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21 New password pointer. 
The address of the password that you want to replace the current password. 


24 String length. 
The length of the character string (maximum 77 bytes) that you want to place in the optional information 
field of the password record. Set this field to zero if you don’t want to add additional information. 





25 String pointer. | 
The address of the character string that is going to be put in the optional information field of the password 
record. Set the address to zero if you don’t want to add additional information. 


Figure 26 (Part 2 of 2). Parameter List for REPLACE Function 
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Notes: 








0 X03'. 
Entry code indicating DELETE function. 


4 Data set name length. 


5 Data set name pointer. 


9 Current password pointer. 
The address of the password that you want to delete. You can delete either a control entry or a 


secondary entry. 


13 Control password pointer. 
The address of the password assigned to the data set when it was placed under protection for the first 
time. The pointer can be 2 bytes of binary zeros if the current password is also the control password. 


16 Number of volumes. 
If the data set is not cataloged and you want to have it flagged as protected, you must specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, you must provide the 


address of a list of volume serial numbers in this field. If this field is zero, the catalog information will be 


used. 


Figure 27. Parameter List for DELETE Function 
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4 Data set name length 9 Current password pointer 


Notes: 







0 X'04'. 
Entry code indicating LIST function. 

1 80-byte buffer pointer. . 
The address of a buffer where the list of information can be returned to your program by the macro 


instruction. 


4 Data set name length. 
5 Data set name pointer. 
9 Current password pointer. 


The address of the password of the record that you want listed. 


Figure 28. Parameter List for LIST Function 
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Return Codes from the PROTECT Macro 


om 
When the PROTECT macro finishes processing, register 15 contains one of the ‘ey 
following return codes: | 
Code Meaning 
0(X'00') The updating of the PASSWORD data set was successfully 
completed. 
4(X'04') The PASSWORD of the data set name was already in the password 
data set. 
8(X'08') The password of the data set name was not in the PASSWORD 
data set. 
12(X'OC') Acontrol password is required or the one supplied is incorrect. 
16(X'10') The supplied parameter list was incomplete or incorrect. 
20(X'14') There was an I/O error in the PASSWORD data set. 
24(X'18')! The PASSWORD data set was full. 
28(X'1C') — The validity check of the buffer address failed. 
32(X'20')2, The LOCATE macro failed. LOCATE’s return code is in register 1, 
and the number of indexes searched is in register 0. 
36(X'24')2 The OBTAIN macro failed. OBTAIN’s return code is in register 1. 
40(X'28')2, The DSCB could not be updated. 
44(X'2C') |The PASSWORD data set does not exist. 
48(X'30')2 Tape data set cannot be protected. 
52(X'32')2 Data set in use. 
56(X'38')2 The data set uses the virtual storage access method (VSAM). 
Notes: 
1 For this return code, a message is written to the console indicating that 
the PASSWORD data set is full. 
2 For this return code, the PASSWORD data set has been updated, but 
the DSCB has not been flagged to indicate the protected status of the 
data set. _ 
4. 
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Chapter 5. Exit Routines 


The detailed information about installation-written exit modules has been moved to 
Data Facility Product: Customization. 


This chapter discussed how exit modules can: 


e Take control before and after direct access device storage management 
(DADSM) processing 


e Take control during Open for a DCB 


e Determine whether a missing data set control block (such as for a data set that 
has been moved to another volume) can be restored to a volume 


e Recover from errors that may occur during the opening, closing, or handling of 
an end-of-volume condition for a data set associated with the user’s task 


e Bypass, limit, or override system-calculated values that assist you in selecting 
optimum DASD data set block size/CI size. 


Chapter 5. Exit Routines 125 





























Chapter 6. System Macro Instructions 


Introduction 


This chapter describes miscellaneous macro instructions that allow you to: 

e Modify control blocks (RDJFCB macro) 

e Obtain information from control blocks and system tables (DEVTYPE macro) 
e Perform track capacity calculations (TRKCALC macro) 

e Allocate a data set based on a partial DSCB (REALLOC macro) 


e Load a message display on an IBM 3480 Magnetic Tape Subsystem 
(MSGDISP macro) 


Before reading this chapter, you should be familiar with the following publication: 


e Assembler H Version 2 Application Programming: Guide contains the 
information necessary to code programs in the assembler language. 


The system macro instructions are described in these functional groupings: 
e Mapping (IEFUCBOB, IEFJFCBN, and CVT) 

¢ Obtaining device characteristics (DEVTYPE) 

« Manipulating the JECB (RDJFCB) 

« Data security (DEBCHK) 

e Manipulating queues (PURGE and RESTORE) 

¢« Performing track capacity calculations (TRKCALC) 

« Allocating a DASD data set (REALLOC) 

e Releasing unused space from a DASD data set (PARTREL) 


¢« Loading a message display on an IBM 3480 Magnetic Tape Subsystem 
(MSGDISP) 
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Mapping System Data Areas 


The IEFUCBOB, IEFJFCBN, and CVT macro instructions are used as DSECT 
expansions that define the symbolic names of fields within the unit control block 
(UCB), job file control block (JFCB), and communication vector table (CVT), 
respectively. , 


The CVT, IEFUCBOB, and IEFJFCBN macro definitions are in a distribution 
library named SYS1.AMODGEN. Before you can issue the macros, you must copy 
them from SYS1.AMODGEN into SYS1.MACLIB (the IEBCOPY utility can be 


used to copy the macros), or SYS1.AMODGEN may be concatenated to the macro 
library before reference is made to SYS1.AMODGEN. 


IEFUCBOB—Mapping the UCB 
This macro instruction defines the symbolic names of the fields in the unit control 


block (UCB). The macro does not include a DSECT statement. However, if you 
specify PREFIX= YES, the DSECT statement is provided. 


The format is: 


[symbol] | IEFUCBOB | [LIST={NO| YES}] 
[,PREFIX={NO | YES}3] 


LIST={NO | YES} 





NO 
specifies that only the UCB prolog is to be printed. 


YES 
specifies that the UCB prolog and the rest of the UCB are to be 
printed. 


PREFIX={NO | YES} 


NO 
specifies that no prefix is to be printed. 


YES 


specifies that the prefix and main body of the UCB are to be printed. 
A DSECT statement is included if you specify PREFIX= YES. 


IEFJFCBN—Mapping the JFCB 


This macro instruction defines the symbolic names of the fields in the job file 
control block (JFCB). The macro does not include a DSECT statement. If you 
require one, code a DSECT statement before the macro statement. 
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The format is: 


IEFJFCBN | [LIST={NO| YES}] 


LIST={NO | YES} 





NO 
specifies that only the JFCB prolog is to be printed. 

YES 
specifies that the JFCB prolog and the rest of the JFCB are to be 
printed. 


CVT—Mapping the CVT 


This macro instruction defines the symbolic names of all fields in the 
communication vector table (CVT). 


The format is: 


[symbol] CVT [DSECT={NO | YES}] 
[,LIST={NO | YES}] 





DSECT={NO | YES} 


NO 
specifies that you do not want a DSECT. 


YES 
specifies that you want a DSECT. 


LIST={NO | YES} 


NO 
specifies that only the CVT prolog is to be printed. 

YES 
specifies that the CVT prolog and the rest of the CVT are to be 
printed. 


Obtaining I/O Device Characteristics 


Use the DEVTYPE macro instruction to request information relating to the 
characteristics of an I/O device, and to cause this information to be placed into a 
specified area. (The results of a DEVTYPE macro instruction executed before a 
checkpoint is taken should not be considered valid after a checkpoint/restart 
occurs.) The IHADVA macro maps the data returned by the DEVTYPE macro. 


The topics that follow discuss the DEVTYPE macro, device characteristics, and 
particular output for particular devices. 
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DEVTYPE Macro Specification 


The format is: Me 


[symbol] | DEVTYPE ddloc-addrx 
yarea-addrx 


[,.DEVTAB] 





For the UCBLIST function, the format is: 


[symbol] | DEVTYPE 


ddloc-addrx 
the name of an 8-byte field that contains the symbolic name of the DD 
statement to which the device is assigned. The name must be left justified in 
the 8-byte field, and must be followed by blanks if the name is fewer than 
eight characters. The doubleword need not be on a doubleword boundary. 





area-addrx 
the name of an area into which the device information is to be placed. If your 
program does not specify the UCBLIST function, the area can be two, five, 
or six fullwords long, depending on whether or not you specify the DEVTAB 
and RPS operands. If your program specifies the UCBLIST function, the gy 
area must be 6 fullwords long. The area must be on a fullword boundary. | 


area-size 
the size of the area into which the device information is to be placed. 


DEVTAB 
This operand is only required for direct access devices. If DEVTAB is 
specified, the following number of words of information is placed in your 
area: 


e For direct access devices: 5 words 
e For non-direct access devices: 2 words 
If you do not code DEVTAB, one word of information is placed in your area 


if the reference is to a graphics or teleprocessing device; for any other type 
of device, two words of information are placed in your area. 


If RPS is specified, DEVTAB must also be specified. The RPS parameter 
causes one additional full word of RPS information to be included with the 


DEVTAB information. 

UCBLIST 
UCBLIST provides a list service in which the caller passes a list and count of a 
the addresses of UCBs. The information returned is always given in 6-word ff * 
entries (one entry per UCB address) regardless of the device type. The ‘eo 
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words that would contain information not applicable to the device for that 
entry are not altered. 


Note: Any reference fora DUMMY data set in the DEVTYPE macro instruction 
will cause eight bytes of zeros to be placed in the output area. Any reference to a 
SYSIN or SYSOUT data set causes X'00000102' to be placed in word 0 and 
32760 (X'00007FF8') to be placed in word 1 in the output area. Any reference 
to a file allocated to a TSO terminal causes X'00000101' to be placed in word 0 
and 32760 (X'00007FF8') to be placed in word 1 in the output area. | 





Device Characteristics Information 


The following information is placed into your area as a result of issuing a 
DEVTYPE macro: 


Word 0 
Describes the device as defined in the UCBTYP field of the UCB. 


Word I 
Maximum block size. For direct access devices, this value is the smaller of 
either the maximum size of a nonkeyed block or the maximum block size 
allowed by the operating system; for magnetic tape devices, this value is the 
maximum block size allowed by the operating system. For all other devices, 
this value is the maximum block size accepted by the device. 


If your program specifies either DEVTAB or UCBLIST, the next three fullwords 
contain the following information about direct access devices: 


Word 2 


Bytes 0-1 The number of physical cylinders on the device, including 
alternates. 


Bytes 2-3 The number of tracks per cylinder. 


Note: Before you use bytes 2 and 3, read the description of 
word 4, byte 1, bit 0. 


Word 3 
Bytes 0-1 Maximum track length. Note that for the IBM 3375 and 
3380 direct access devices, this value is not equal to the value 
in word | (maximum block size) as it is for other IBM direct 
access devices. 
Note: Before using bytes 2 and 3, read the description of word 4. 
Byte 2 Block overhead, keyed block—the number of bytes required 
for gaps and check bits for each keyed block other than the 


last block on a track. 


Byte 3 Block overhead—the number of bytes required for gaps and 
check bits for a keyed block that is the last block on a track. 
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Bytes 2-3 


Word 4 


Byte 0 


Byte 1 


Bytes 2-3 
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Block overhead—the number of bytes required for gaps and 
check bits for any keyed block on a track including the last 
block. Use of this form is indicated by a 1 in bit 4, byte 1 of 


word 4. 


Basic overhead—the number of bytes required for the count 
field. Use of this form is indicated by a 1 in bit 3, byte 1 of 


word 4. 


Block overhead, block without key—the number of bytes to 
be subtracted from word 3, bytes 2 or 3 or bytes 2 and 3, if a 
block is not keyed. 


If bit 3, byte 1 of word 4 is 1, this byte contains the modulo 
factor for a modulo device. 


Bit 0 


Bit 1 


Bits 2-3 


Bit 3 


Bit 4 


Bits 5-6 


Bit 7 


If on, the number of cylinders, as indicated in 
word 2, bytes 0 and 1 are invalid. 


Reserved. 


If on, indicates a 3380 is attached to a 3880 
Model 13 or 23. 


If on, indicates a modulo device (3375, 3380). 
For information on how to calculate the 
number of data bytes required for a data 
block for a modulo device, see the device data 
in Data Administration Guide. 


If on, bytes 2 and 3 of word 3 contain a 
halfword giving the block overhead for any 
block on a track, including the last block. 


Reserved. 


If on, a tolerance factor must be applied to all 
blocks except the last block on the track. 


Tolerance factor—this factor is used to calculate the effective 
length of a block. The calculation should be performed as 


follows: 


Step 1 


Step 2 


add the block’s key length to the block’s data 
length. 


test bit 7 of byte 1 of word 4. If bit 7 is 0, 
perform step 3. If bit 7 is 1, multiply the sum 
computed in step 1 by the tolerance factor. 
Shift the result of the multiplication 9 bits to 
the right. 





Step 3 add the appropriate block overhead to the 
value obtained above. 





If bit 3, byte 1 of word 4 is 1, bytes 2 and 3 contain the 
overhead for the data or key field. 





If your program specifies DEVTAB and RPS, or specifies UCBLIST, the 
next fullword contains the following information: 


Word 5 
Bytes 0-1 RO overhead for sector calculations 
Byte 2 Number of sectors for the device 
Byte 3 Number of data sectors for the device 


Figure 29 on page 134 shows the output for each device type that results from 
issuing the DEVTYPE macro. 


Note: If your program specifies UCBLIST, the output consists of one 6-word 
entry for every UCB address contained in the UCB list. 


Return Codes from the DEVTYPE Macro 
Control is returned to your program at the next executable instruction following the 


a DEVTYPE macro instruction. Register 15 contains a return code from the 
: DEVTYPE macro. The return codes and their meanings are as follows: 


Code Meaning 


00(X'00') Indicates that the information concerning the ddname you specified 
has been successfully moved to your work area. 


04(X'04') Indicates that the ddname you specified was not found. 


Chapter 6. System Macro Instructions 133 


Record Size 





(Word 1, in DEVTAB (Words 2, 3, and | RPS (Word 5, 
Decimal) 4, in Hexadecimal) in Hexadecimal) 


[asso Reader ‘(| 80 | NovApplabie [Now Appable 
[asso Reader w/c [80 NotAppizabie [Not Appcable 
[asso Punch [80 | Not Applicable [Not Appable 
[2540 Punch w/Gi [80 | Nev Applicable | Not Applicable 
[aso1 Reader [80 | NovAnplabie [Nou Appcable 
[aso1 Reader w/c [80 | Not Anplabie | Not Appcable 


| 3890 Document Not Applicable Not Applicable 
Processor 


[as0s Reader ‘(80 | NevAnplae_————=«(NvApliabie 
[3505 Reader w/cr [80 | Nov applicable | Nov Applicable 
faszs punch [80 [NovArplcable___[NowAppcable 


2305 Model 2 14660 006000083 A0A01215B080200 | 0140B4B1 
Fixed-Head Storage 


3330/3333 Disk Storage 13030 019B0013336DBFBF38000200 | OOED807C 


3330V MSS Virtual 13030 019B0013336DBFBF38000200 | OOED807C 
Volume 


Figure 29 (Part 1 of 2). Output from DEVTYPE Macro 
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Maximum 
Record Size 





IBM (Word 1, in DEVTAB (Words 2, 3, and RPS (Word 5, 
Device! 2 Decimal) 4, in Hexadecimal) in Hexadecimal) 


3330 Model 11 (or 3333 13030 032F0013336DBFBF38000200 | OOED807C 
Model 11) Disk Storage 

3340 Disk Storage (35 8368 015D000C2157F2F24B000200 | 0125403D 
megabytes) 

3340/3344 Disk Storage 8368 0230001E4B36010B52080200 | 0125403D 
(70 megabytes) 


3350 Disk Storage 19069 0230001E4B36010B52080200 | 0185807B 
3375 Disk Storage 32760 03BFOO0C8CA000E0201000BH 0340C4BB 


3380 Models A04, AA4, 32760 0376000FBB6001002010010B | 0O4EODED6 
and B04 Disk Storage 


3380 Models A04, AA4, 32760 0376000FBB6001002030010B | O4EODED6 
and B04 Disk Storage 
(attached to a 3880 
Model 13 or 23) | 
3380 Models AD4 and 32760 0376000FBB6001002010010B | O4EODED6 
BD4 Disk Storage 
3380 Models AE4 and 32760 06EBO00FBB6001002010010B | O4EODED6 
an BE4 Disk Storage 
( 2250 Model 3 Display Not Applicable Not Applicable 

: Unit 
1030,1050,83B3, Not Applicable | Not Applicable Not Applicable 
TWX,2250,S360 | 


115A,1130 Not Applicable | Not Applicable Not Applicable 


2780 Not Applicable | Not Applicable Not Applicable 
2740 Not Applicable | Not Applicable Not Applicable 


Figure 29 (Part 2 of 2). Output from DEVTYPE Macro 





i 
‘ 
i 
1 
I. 





Notes to Figure 29: 


1 CI—card image feature; d.c_—data conversion; d.d.—dual density; 
p.e.—phase encoding; UCS—universal character set; w/—with. 


2 Although certain models can have a larger line size, the minimum line size is 
assumed. 


3 The IBM 3800 Printing Subsystem can print 136 characters per line at 
10-pitch, 163 characters per line at 12-pitch, and 204 characters per line at 
15-pitch. The machine default is 136 characters per line at 10-pitch. 


4 The IBM 4248 Printer returns 132 characters even if the 168 Print Position 
Feature is installed on the device. 
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DEVTYPE—List Form 0 
The list form of the DEVTYPE macro is only valid with the UCBLIST function. It eed 
is used to construct an empty parameter list. By specifying MF=L you construct a 
parameter list, and you can subsequently supply the values by specifying the 
execute form of the macro. 


, (area-addrx,area-size) 


»,UCBLIST=YES 
MF=L 





name! 
label of the parameter list to be constructed. It must also be specified in the 
corresponding MF=E form. 


DEVTYPE—Execute Form 


The execute form of the DEVTYPE macro is only valid with the UCBLIST 
function. It can be used to modify a parameter list and call the DEVTYPE 
function. 


[namel] | DEVTYPE ,(area-addrx,area-size) 


»UCBLIST=(ucbl-addrx,ucbl-num) 
JMF=(E,name/) 





name 1 Me 
label of the parameter list constructed by the corresponding MF=L form. 


Reading and Modifying a Job File Control Block 


To accomplish the functions that are performed as a result of an OPEN macro 
instruction, the open routine requires access to information that you have supplied 
in a data definition (DD) statement. This information is stored by the system in a 
job file control block (JFCB). 


In certain applications, you may find it necessary to modify the contents of a JFCB 
before issuing an OPEN macro instruction. For example, suppose you are adding 
records to the end of a sequential data set. You might want to add a secondary 
allocation quantity to allow the existing data set to be extended when the space 
currently allocated is exhausted. To assist you, the system provides the RDJFCB 
macro instruction. This macro instruction causes a specified JFCB to be moved 
from the scheduler work area (SWA), where it is stored, to an area specified in an 
exit list. The use of the RDJFCB macro instruction with an exit list is shown under 
“Example” on page 138. When you subsequently issue the OPEN macro 
instruction, you must indicate, by specifying the TYPE=J operand, that you want 
to open the data set using the JFCB in the area you specified. 


The RDJFCB macro also allows you to retrieve allocation information (all JFCBs £. 


and all volume serial numbers) for the data sets in a concatenation. You may either ‘e 7 
select data sets or, by default, retrieve the information for all data sets in the - 
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concatenation. Figure 33 on page 146 illustrates how you can use RDJFCB to 
retrieve this information. 


Caution: If you set the bit JECNWRIT in the field JECBTSDM to 1 before you 
issue the OPEN macro instruction, the JFCB is not written back to the SWA at the 
conclusion of open processing. OPEN TYPE=J normally moves your program’s 
modified copy of the JFCB to the scheduler work area (SWA), replacing the 
system copy. To ensure that this move is done, your program must set bit zero (0) 
of the JECBMASK +4 field to 1. The JECBMASK format is shown in the Internal 
Data Areas section of Open/Close/EOV Logic. If the user JFCB, which the system 
used to open the data set, is not written back to SWA (JFCNWRIT set on), then 
errors may occur during EOV or close processing. 


Some of the modifications that are commonly made to the JFCB include: 


e Moving the creation and expiration date fields of the DSCB into the JFCB (see 
‘‘Using RDJFCB for MSS Virtual Volumes” on page 140). 


e Moving the secondary allocation quantity from the DSCB into the JFCB (see 
‘Using RDJFCB for MSS Virtual Volumes’’ on page 140). 


e Moving the DCB fields from the DSCB into the JFCB. 


e Adding volume serial numbers to the JFCB (see ““Using RDJFCB for MSS 
Virtual Volumes’”’ on page 140 and ““RDJFCB Security” on page 140). 


Volume serial numbers in excess of five are written to the JECBX (extension) 
located in the SWA. The JFCBX cannot be modified by user programs. 


e Modifying the data set sequence number field in the JFCB. 


e Modifying the number-of-volumes field in the JFCB (see ‘‘Using RDJFCB for 
MSS Virtual Volumes” on page 140). 


e Setting bit JFCDQDSP in field JECBFLG3 to invoke the tape volume DEQ at 
demount facility (see ‘‘DEQ at Demount Facility for Tape Volumes” on 
page 147). 


e Modifying the JECRBIDO field in the JFCB to cause high-speed positioning to 
a specific data block on a 3480 tape volume. 


RDJFCB—Read a Job File Control Block 


The RDJFCB macro instruction causes a job file control block (JFCB) to be 
moved from the SWA (scheduler work area) into an area of your choice as — 
identified via the EXLST parameter of the DCB macro for each data control block 
specified. 


[symbol] RDJFCB | (dcb-address 
sl(options)],...) 





Chapter 6. System Macro Instructions 137 





dcb-address,|(options)| 


(same as the dcb-address, option1, and option2 operands of the OPEN a 
macro instruction, as shown in Data Administration: Macro Instruction ae 
Reference), except for the MODE operand, which is not valid with the 

-_ RDJFCB macro. 


The option operands do not affect RDJFCB processing. You can, however, 
specify them in the list form of the RDJFCB macro instruction and refer to 
the generated parameter list with the execute form of the macro. 


Example: In Figure 30, the macro instruction at EX1 creates a parameter list for 
two data control blocks: INVEN and MASTER. In creating the list, both data 
control blocks are assumed to be opened for input; option2 for both blocks is 
assumed to be DISP. The macro instruction at EX2 moves the system-created 
JFCBs for INVEN and MASTER from the SWA into the area you specified, thus 
making the JFCBs available to your problem program for modification. The macro 
instruction at EX3 modifies the parameter list entry for the data control block 
named INVEN and indicates, through the TYPE=J operand, that the problem 
program is supplying the JFCBs for system use. 


EX1 RDJFCB (INVEN, ,MASTER) ,MF=L 
EX2 RDJFCB MF=(E,EX1) 
EX3 OPEN (, (RDBACK, LEAVE) ) , TYPE=J,MF=(E,EX1) 
INVEN DCB EXLST=LSTA,... 
MASTER DCB EXLST=LSTB,... 
LSTA DS OF 
DC X'O7' 
DC AL3 (JFCBAREA) 
JFCBAREA DS OF,176C 
LSTB DS OF 


Figure 30. Sample Code Using RDJFCB Macro 





Multiple data control block addresses and associated options may be specified in 
the RDJFCB macro instruction. This facility makes it possible to read several job 
file control blocks in parallel. 
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An exit list address must be provided in each DCB specified by an RDJFCB macro 
instruction. Each exit list must contain an active entry that specifies the virtual 
storage address of the area into which a JFCB is to be placed. 





| Two kinds of JFCB entries may appear in the exit list. Each is briefly explained in 
| the following text. A full discussion of the exit list and its use is contained in Data 
| Facility Product: Customization. 





| Type 07 JFCB Exit List Entry 


| The type 07 JFCB exit list entry allows a variety of functions to the user, as 
| described in the following text. 


| The format of the Type-07 JFCB exit list entry is as follows: 


Types of Hexadecimal 
Exit List Code (High- Contents of Exit List Entry 
Entry Order Byte) (Low-Order Bytes) 


Job file Address of a 176-byte area to be provided 
control if the RDJFCB or OPEN (TYPE=J) 


block macro instruction is used. This area must 
begin on a fullword boundary and must be 
located within the user’s region. Also, 
users running in 31-bit addressing mode 
must ensure that this area is located below 
16 megabytes virtual. 





The virtual storage area into which the JFCB is read must be at least 176 bytes 
| long. Each exit list entry must be 4 bytes long. The system recognizes only the first 
| occurrence of an exit list entry code. Indicate the end of the exit list by setting the 
| high order bit in the entry code to 1. 


The DCB may be either open or closed when this macro instruction is executed. 

If the JFCB is read successfully for all DCBs in the parameter list, return code 0 is 
placed in register 15. If the JFCB is not read for any of the DCBs because the 
DDNAME is blank, or a DD statement is not provided, return code 4 is placed in 
register 15. 


Warning: The following errors cause the results indicated: 


Return code 4 is placed in register 15. | 


A DD statement has not been 
A write-to-programmer is issued, the 


provided. 

DDNAME field in DCB is blank. 
request for this DCB is ignored, and 
return code 4 is placed in register 15. 
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A virtual storage address has not Abnormal termination of task. 
been provided. 


If you want to open a VTOC data set to change its contents (that is, open it for 
OUTPUT, OUTIN, INOUT, UPDAT, OUTINX, or EXTEND), your program 
must be authorized under the Authorized Program Facility (APF). APF provides 
security and integrity for your data sets and programs. Details on how you 
authorize your program are provided in System Programming Library: Supervisor 
Services and Macro Instructions. 


If the RDJFCB routine fails while processing a DCB associated with your RDJFCB 
request, your task is abnormally terminated. None of the options available through 
the DCB ABEND exit, as described in Data Facility Product: Customization, are 
available when a RDJFCB macro instruction is issued. 


When using concatenated data sets, the RDJFCB routine modifies only the first 
JEFCB. 


Using RDJFCB for MSS Virtual Volumes: Care must be taken in using RDJFCB if 
the data set resides on MSS virtual volumes such that: 


e The expiration date added does not conflict with other volumes within the 
specified MSVGP. 


e The secondary allocation quantity should be in cylinder increments and be a 
multiple or submultiple of the primary allocation quantity to avoid 
fragmentation. 


e The number of volumes must not exceed the number available in the specified 
MSVGBP. 


e Any volume serial numbers added to the JFCB should exist in the MSVGP. 


RDJFCB Security: The volume serial numbers specified in the user-supplied JFCB 
will be compared with the volume serial numbers in the system JFCB located in the 
SWA. Each different volume serial number will be enqueued exclusively. The 
volumes will stay enqueued until the job step terminates, because the close routines 
will not dequeue the volumes. If the job step already has the volume open, OPEN 
TYPE=J will continue. If the volume is enqueued by another job step, a 413 
abend will occur with a return code of 04. 


Some JFCB modifications can compromise the security of existing 
password-protected data sets. The following modifications are specifically not 
allowed, unless the program making the modifications is authorized or can supply 
the password: 


e Changing the disposition of a password-protected data set from OLD or MOD 
to NEW. 


e Changing the data set name of one or more of the volume serial numbers when —_ 
the disposition is NEW. 
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e« Changing the label processing specifications to bypass label processing. 


Note: An authorized program is one that is either in supervisor state, executing in 
one of the system protection keys (keys 0 through 7), or authorized under the 
Authorized Program Facility. 


RDJFCB Use by Authorized Programs: \f you change the data set name in the 
JEFCB, you should do a system enqueue on the major name of “SYSDSN”’ for the 
substituted data set name. To use the correct interface with other system functions 
(for example, partial release), the ENQUEUVE macro should include the TCB of 
the initiator and the length of the data set name (with no trailing blanks). When 
you complete processing of the data set, you should use the DEQ macro to release 
the resources. If the substituted data set name is enqueued by another job step, a 
913 abend occurs with a return code of X'1C'. 


Using RDJFCB to Process a Multivolume Direct Data Set: This use of RDJFCB and 
OPEN TYPE=J permits your program to process a multivolume data set. To do so, 
your program must cause the open routines to build a data extent block for each 
volume and issue mount messages for them. Your program must use the RDJFCB 
macro to read in the JFCB, and open each volume of the data set. The following 
code illustrates the procedure: 
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RDJFCB DCB 1 READS IN THE JFCB wa 3 
SR R3,R3 CLEARS REG 3; IT WILL a 
* HOLD COUNT OF VOLS TO 
* BE OPENED 
IC R3,JFCBNVOL PUTS # OF VOLS 
* | IN REG 3 
LA R4,DCB1 R4 POINTS TO DCB FOR 
* VOL TO BE OPENED 
LA R5,1 PUTS SEQUENCE # OF 
* FIRST VOL TO BE 
* OPENED IN REG 5 
LOOP EQU * 
STH R5 ,JFCBVLSQ PUTS SEQ # OF VOL 
x TO BE OPENED WHERE 
* | OPEN RTNS LOOK 
OPEN ((R4) ,OUTPUT) , TYPE=J OPENS ONE VOL 
* NOTE THAT THE TYPE=J OPTION OF THE MACRO MUST BE USED 
LA R4,DCB2-DCB1(R4) INCREMENT REG 4 TO 
* POINT TO THE DCB FOR 
* THE NEXT VOL TO BE 
* OPENED 
LA R5,1(R5) INCREMENT TO SEQ # OF 
* NEXT VOL TO BE OPENED 
BCT R3 , LOOP LOOP UNTIL ALL VOLS 
* OPEN 
JFCB DS CL176 JFCB READ IN HERE 
ORG JFCB+70 -_ 
JFCBVLSQ DS H SEQ # OF VOL TO BE -* 
. OPENED 8 
ORG JFCB+117 
JFCBNVOL DS FL1 # OF VOLS IN DATA SET 
ORG 
* MAPPING MACRO IEFJFCBN MAY ALSO BE USED 
DCB1 DCB DDNAME=SYSUT1,MACRF=(E) , EXLST=EXITS , DSORG=PS 
DCB2 DCB DDNAME=SYSUT1,MACRF=(E) , EXLST=EXITS , DSORG=PS 
DCB3 DCB DDNAME=SYSUT1,MACRF=(E) , EXLST=EXITS , DSORG=PS 
DCB4 DCB DDNAME=SYSUT1,MACRF=(E) , EXLST=EXITS , DSORG=PS 
DCB5 DCB DDNAME=SYSUT1,MACRF=(E) , EXLST=EXITS , DSORG=PS 
* THIS PROCEDURE WORKS FOR 5 VOLS OR LESS; THE JFCB 
* EXTENSION, WHICH IDENTIFIES ADDITIONAL VOLS, CAN'T 
* BE READ IN 
EXITS DS OF 
DC X'87' ,AL3 (JFCB) 87 IDENTIFIES THIS AS 
* THE EXIT LIST ENTRY 
* THAT SHOWS WHERE JFCB: 
* WILL BE READ IN 
Type 13 JFCB Exit List Entry 
The type 13 JFCB exit list entry allows you to retrieve selected allocation 
information, as described in the following text. 
The format of the type 13 JFCB exit list entry is as follows: _ 
4 . 
«2 
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Types of Hexadecimal 
Exit List Code (High- Contents of Exit List Entry 
Entry Order Byte) (Low-Order Bytes) 


Job file Address of an allocation retrieval list. 

control OPEN TYPE=J does not recognize this 

block exit list entry. This entry allows you to use 
RDJFCB to obtain copies of the JFCBs 
for data sets in a concatenation, and lists 
of all the volume serial numbers for those 
data sets. You may select JFCBs in the 
concatenation or by default, retrieve all of 
them. See Figure 31 on page 144 for the 
allocation retrieval list format, and 
Figure 33 on page 146 for an example of 
usage. 





Using RDJFCB to Retrieve Allocation Information: RDJFCB uses DCB exit list 
entry type 13 to retrieve allocation information (JFCBs and volume serial 
numbers) for concatenated data sets. The exit list entry code is X'13', and is 
defined as “retrieve allocation information.” The second through fourth bytes of 
this entry must point to an ‘‘Allocation Retrieval List,’’ as described in Figure 31 
on page 144. When you issue RDJFCB, this DCB exit list entry causes retrieval of 
JFCBs for the specified concatenated data sets, and lists of all volume serial 
numbers for these data sets. You may either select JFCBs in the concatenation or 
by default, retrieve all of them. OPEN TYPE=J does not recognize this exit list 
entry. RDJFCB uses the parameter list to receive and return information about the 
request. You may use the IHAARL macro (shown below) to generate and map the 
allocation retrieval list. 


[symbol] IHAARL | [DSECT=}{YES | NO}] 
[,PREFIX=prefix] 
[.DESCR={YES | NO}] 


DSECT={YES | NO} 
specifies whether the symbol at the beginning of the generated area appears 
on a DSECT instruction or a DC instruction. For DSECT=NO, the symbol 
appears on a DC instruction. The default is DSECT=YES. 





PREFIX= prefix 
allows you to invoke the macro more than once per assembly. Specifies a 
character string with which all generated symbols are to be prefixed. Do not 
specify delimiters, such as quotation marks. If you omit this operand or 
specify a null value, the prefix defaults to the characters ARL. 


DESCR={YES | NO} 


specifies whether the macro expansion includes the macro description 
(prolog). The default is DESCR=NO. 
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Name 


Figure 31 and Figure 32 describe the formats of the allocation retrieval list and 
allocation retrieval area, respectively. 


Offset 


Bytes 


Description 


The Following Fields Are Set by the Caller of RDJFCB: 


ARLLEN 


ARLIDENT 


ARLOPT1 


ARLLANY 


ARLRSVD1 | 
ARLRETRV 


ARLFIRST 


00(X'00') 
02(X'02') 
04(X'04') 


05(X'05') 
12(X'0C') 


14(X'0E') 


The Following Fields Are Set by RDJFCB: 


ARLAREA 
ARLPOOL 
ARLRLEN 
ARLRTRVD 
ARLCONC 


ARLRCODE 


ARLRSVD2 


Figure 31. 


16(X"'10') 
20(X'14') 
21(X'15") 
24(X'18') 
26(X'1A"') 


28(X'1C') 


29(X'1D') 


NO We 


7 


Format of the Allocation Retrieval List 
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Length of this area. Value must be 36 or more. 
EBCDIC 'AR' 

Option byte. 

Allocation retrieval area must be below 16Mb line. 
Allocation retrieval area may be above 16Mb line. 
Reserved. Must be zero. 

Reserved. Must be zero. 

Number of data sets for which to retrieve information. If 
0, retrieve all in the concatenation. 

Number of first data set in concatenation for which to 
retrieve information. O or 1 specifies retrieval of 
information beginning with first data set in the 
concatenation. 


Address of allocation retrieval area. See Figure 32. 
Storage subpool containing allocation retrieval area. 
Length of allocation retrieval area. 

Number of concatenated data sets for which JFCBs were 
retrieved. 

Number of concatenated data sets. If no concatenation, 
this value is 1. 

Reason Code: 


0 = Requested information was read. 
The following reason codes are related to return code 8: 
4 = ARLFIRST is greater than ARLCONC. 
= Insufficient storage to read information. 
ARLPOOL and ARLRLEN describe what could not 


be obtained. 
Reserved. Used by RDJFCB. 





é 

4 ; 
4 vs 
M a 








Offset Bytes 





Description 


0O(X'00') 2 Length of the information for this data set (including this field). The 
length is rounded up to a multiple of four so the starting address of the 
allocation retrieval area plus the value in the length field designates the 
address of the retrieval area for the next data set in the concatenation, if 
requested. 

02(X'02') 2 Reserved. Set to zero. 

04(X'04') 176(dec) JFCB 

180(X'B4') variable Sixth and subsequent volume serial numbers. Determined by the value in 


JFCBNVOL. If the number of volume serial numbers is fewer than the 
specified volume count, entries at the end of the list may contain all 
blanks. If the first byte of an entry is X'FF', the JCL specified 
VOL=REF and the volume could not be determined. 


Figure 32. Format of the Allocation Retrieval Area 





Return code 0 indicates that RDJFCB has filled in the allocation retrieval list fields. 
When you have finished using information from the retrieval areas, you should 
issue FREEMAIN to free the areas. To determine whether the release of the Data 
Facility Product on your system is capable of using exit list entry type X'13' to 
retrieve allocation information, set the ARLAREA field in the allocation retrieval 
list to zeros before issuing RDJFCB. If the ARLAREA is still zeros and the 
ARLRCODE field contains reason code 00 when RDJFCB returns control to your 
program, your release of DFP does not support this function. 


Example: In Figure 33 on page 146, the macro instruction at ALLOCINF creates 
a parameter list for one DCB (INDCB), assumed to be open for input. The JFCBs 
and volume serial numbers are retrieved for all data sets allocated to DD name 
SYSLIB. 
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*** TCL FOR FOLLOWING INVOCATION OF RDJFCB: \ 





Wo 
//SYSLIB DD DISP=SHR, DSN=DEPT61.ROUTINES 
ff DD DISP=SHR,DSN=CORPORAT. ROUTINES 
ye DD DISP=SHR,DSN=SYS1.FORTLIB 
*** EXAMPLE CODE TO INVOKE RDJFCB ALLOCATION INFORMATION RETRIEVAL: 
* GET A COPY OF THE JFCB FOR THE FIRST OR ONLY DATA SET ALLOCATED 
* TO SYSLIB AND TRY TO READ THE JFCBS AND VOLUME SERIAL NUMBERS 
* FOR ALL DATA SETS ALLOCATED TO SYSLIB. 
ke 
ALLOCINF RDJFCB (INDCB) 
LTR R15,R15 TEST RDJFCB RETURN CODE 
BNZ NOJFCB BRANCH IF INFORMATION NOT AVAILABLE 
ICM R1,X'F',SLBAREA GET AND TEST ADDRESS OF ARL 
BZ OLDSYSTM GO IF SYSTEM DOES NOT SUPPORT ARL 
USING SLBSTRT,R1 ESTABLISH ADDRESSABILITY TO AREA 
CLI SLBRCODE, 0 TEST RDJFCB REASON CODE 
BNE NOJFCB BRANCH IF INFORMATION NOT AVAILABLE 
* 
* LOOP THROUGH THE JFCBS IN THE AREA TO WHICH SLBAREA POINTS. 
* CODE CAN BE INSERTED HERE TO PRINT THE DATA SET NAMES AND 
* VOLUME SERIAL NUMBERS. 
OLDSYSTM DS OH ROUTINE TO HANDLE JUST LIBJFCB 
. a 
* : 
NOJFCB DS OH ROUTINE TO HANDLE INABILITY TO GET THE ibe 
* JFCB. THE DATA SET MAY NOT BE ALLOCATED. 
: : 
SLBOPNX DS OH DCB OPEN EXIT ROUTINE FOR SYSLIB. 
* HANDLES RECFM, LRECL, AND BLKSIZE. 
INDCB DS DSORG=PO , DDNAME=SYSLIB,MACRF=R, SYNAD=INERROR, X 
EXLST=INEXLST 
INEXLST DC OF'O',xX'O5' ENTRY CODE FOR OPEN EXIT ROUTINE 
DC AL3 (SLBOPNX) ADDR OF DCB OPEN EXIT ROUTINE 
DC x’ 13? ENTRY CODE TO RETRIEVE ALLOCATION 
* INFORMATION 
DC AL3 (SLB) ADDR OF ALLOCATION RETRIEVAL LIST 
DC X'87' ENTRY CODE TO RETRIEVE FIRST JFCB AND 
* INDICATE LAST ENTRY IN LIST 
DC AL3 (LIBJFCB) ADDR OF JFCB FOR FIRST DATA SET 
* 
* AN ALLOCATION RETRIEVAL LIST FOLLOWS, POINTED TO BY DCB EXIT LIST. 
* 
SLBSTRT IHAARL DSECT=NO, PREFIX=SLB 
DC OF'O' 
LIBJFCB DC CLh176" * FIRST JFCB 
Figure 33. Sample Code Retrieving Allocation Information. THAARL PREFIX=SLB requires Assembler H. 
qo 
(go 
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( DEQ at Demount Facility for Tape Volumes 


This facility is intended to be used by long-running programs that create an 
indefinitely long tape data set (such as a log tape). Use of this facility by such a 
program permits the processed volumes to be allocated to another job for 
processing (such as data reduction). This processing is otherwise prohibited unless 
the indefinitely long data set is closed and dynamically unallocated. 


You may invoke this facility only through the RDJFCB/OPEN TYPE=J interface 
by setting bit JFCDQDSP (bit 0) in field JECBFLG3 (offset 163 or X'A3') to 1. 
The volume serial of the tape is dequeued when the volume is demounted by OPEN 
or EOV with message IEC502E when all the following conditions are present: 





SS RS SESE SET OOS SRR EO PLS E SSS 5 A a TS SST Sep a oe eas ore eee es sz — parent ae pueecrre 


e The tape volume is verified for use by OPEN or EOV. 
e JFCDQDSP is set to 1. 


¢« The program is APF authorized (protect key and supervisor/problem state are 
not relevant). 





e The tape volume is to be immediately processed for output. That is, either 
OPEN verifies the volume and the OPEN option is OUTPUT, OUTIN, or 
OUTINX; or EOV verifies the volume and the DCB is opened for OUTPUT, 
OUTIN, INOUT, or EXTEND, and the last operation against the data set was 
an output operation (DCBOFLWR is set to 1). 


ad, Note that, in order for EOV to find JECDQDSP set to 1, the program must not 
( | inhibit the rewrite of the JFCB by setting bit 4 of JFECBTSDM to 1. 


The tape volume is considered verified after file protect, label type, and density 
conflicts have been resolved. The volume is dequeued when demounted after this 
verification, even if further into OPEN or EOV processing the volume is rejected 
because of expiration date, security protection, checkpoint data set protection, or 
an I/O error. 


When the volume serial is dequeued, the volume becomes available for allocation to 
another job. However, because the volume DEQ is performed without unallocating 
the volume, care must be exercised both by the authorized program and the 
installation to prevent misuse of the DEQ at demount facility. A discussion of such 
misuse follows. 


1. The authorized program must not close and reopen the data set using the tape 
volume DEQ at demount facility. If it does, one of the following can occur: 


a. The dequeued volume may be mounted and in use by another job. When 
the volume is requested for mounting, for the authorized program, the 
operator is unable to satisfy the mount. Therefore, the operator must 
either cancel the requesting job, cancel the job using the volume, wait for 
the requesting job to time out, or wait for the job using the volume to 
terminate. 


b. The dequeued volume may be allocated to another job but not yet in use. 
The operator mounts the volume to satisfy the mount request of the 
authorized job. When the volume is requested for mounting by the other 





Chapter 6. System Macro Instructions 147 


job, the operator is unable to satisfy the mount request, and is faced with 
the same choices as in a, above. ‘ 


c. The dequeued volume may not yet be allocated to another job and the 
volume is mounted to satisfy the mount request of the authorized job. 
Another job may allocate the volume and, when the volume is requested 
for mounting, the situation is the same as in b, above. 


It is the responsibility of the installation that permits a program to run with 
APF authorization to ensure that it does not close and reopen a data set using 
the DEQ at demount facility. 


2. Care should be exercised when an authorized program uses the DEQ at 
demount facility (data set 1) but processes another tape data set (data set 2). 
Assume the same volume serial numbers have been coded in the DD 
statements for data set 1 and data set 2. As the volumes of data set 1 are 
demounted, they are dequeued even though those volumes may yet be 
requested for data set 2. All the problems explained in a, b, and c in 1, above, 
may occur as data set 2 and another job contend for a dequeued volume. 


This problem should not occur, given the intended use of the DEQ at demount 
facility; that is, a long-running application creating an indefinitely long tape 
data set. This type of application is not normally invoked through batch 
execution with user-written DD statements. 


3. After a volume has been demounted and dequeued because of the DEQ at 
demount facility, the volume is not automatically rejected by the control gs 
program when mounted in response to a specific or nonspecific mount request. : 
Without the use of the facility, the control program can recognize (bythe = © : 
ENQ) that the volume is in use, and reject the volume. Therefore, operations 
procedures, in effect to prevent incorrect volumes from being mounted, should 
be reviewed in the light of reduced control program protection from such errors 
when the DEQ at demount facility is used. Specifically, if a volume is 
remounted for an authorized program and the volume had been used previously 
by that authorized program, duplicate volume serial numbers will exist in the 
JFCB, and the control program will be unable to release the volume during 
EOV processing. 


4. Checkpoint/restart considerations are discussed in Checkpoint/ Restart User’s 
Guide. | 


OPEN—Initialize Data Control Block for Processing the JFCB 


The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. 


A full explanation of the operands of the OPEN macro instruction is contained in 
Data Administration: Macro Instruction Reference. The TYPE=J option, because it 
is used in conjunction with modifying a JFCB, should be used only by the system 
programmer or under the system programmer’s supervision. 


The parameters of the OPEN TYPE=J macro instruction are: > 
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[symbol] OPEN (dcb-addr 
s[(options)],...) 
[,.TYPE=J] 





TYPE=J | 
specifies that, for each data control block referred to, you have supplied a 
job file control block (JFCB) to be used during initialization. A JFCB is an 
internal representation of information in a DD statement. 


During initialization of a data control block, its associated JFCB may be 
modified with information from the data control block or an existing data set 
label or with system control information. 


The system always creates a job file control block for each DD control 
statement. The job file control block is placed in the SWA (scheduler work 
area). Its position, in relation to other JFCBs created for the same job step, 
is noted in a table in virtual storage. 


When the TYPE=J operand is specified, you must also supply a DD 
statement. However, the amount of information given in the DD statement is 
at your discretion, because you can modify many fields of the system-created 
job file control block. If you specify DUMMY on your DD statement, the 
open routine will ignore the JECB DSNAME and open the data set as 
dummy. (See Figure 30 on page 138 for an example of coding that 
modifies a system-created JFCB.) 


( Notes: 
1. The DD statement must specify at least: 


e Device allocation (refer to JCL User’s Guide for methods of preventing share 
status) 


e A ddname corresponding to the associated data control block DCBDDNAM 
field 


| 2. The MODE operand is not shown here because it is not allowed with the TYPE=J 
| operand of the OPEN macro instruction. 


High-Speed IBM 3480 Positioning 


High-speed positioning for 3480 tape drives is available when opening a tape data 
set on an IBM standard-labeled tape for either EXTEND (OUTINX, EXTEND, or 
DISP=MOD), or when opening to the beginning of such a data set. To invoke 
high-speed positioning, your program must modify certain fields in the JFCB and 
use OPEN TYPE=J to open the data set. 


You should use the following procedure to modify the JFCB: 


1. Issue the RDJFCB macro to have the system move the JFCB into your work 


( area. 
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2 Set the JFCPOSID flag in the JECBFLG3 flag byte to indicate that you are 
providing a block ID for a high speed search. 


3. Move the block ID into the JECRBIDO field of the JFCB. If you are opening 
to the beginning of a data set, use the block ID of the first header label record 
of that data set. If you are opening to the end of a data set (for example, to 
extend it), use the block ID of the tape mark immediately following the last 
block of user data in that data set. 


4. Issue the OPEN TYPE=J macro to have the system use your modified JFCB. 


After the tape is positioned, OPEN processes the trailer labels for the data set 
being extended. 


If you set the JECPOSID flag off, OPEN positions the volume normally, as though 
the high-speed positioning feature were not active. 


If you set the JECPOSID flag on, but do not provide a block ID in the JECRBIDO 
field, OPEN positions the volume normally and does one of the following: 


e If you are opening to the beginning of a data set, OPEN inserts the block ID of 
the first header label record of that data set into the JFECRBIDO field. 


. if you are opening to the end of the data set, OPEN inserts the the block ID of 
the tape mark immediately following the last block of user data for that data 
set into the JECRBIDO field. 


If the JECPOSID flag is on during CLOSE processing, CLOSE inserts the block ID 
for the first header label record of the next data set (which may not exist) into the 

JFCRBIDC field. Therefore, if you deallocate the 3480 device and want to use the 
current block ID for subsequent processing, you must save the block ID before you 


CLOSE the data set. 

OPEN resets the JECPOSID flag if either of the following conditions exists: 

e Your program issues an OPEN which is not TYPE=J. 

¢« The requested tape volume is not an IBM standard-labeled volume. 

e The requested unit is not a buffered tape device 

Notes: 

1. If you specify dynamic unallocation (with SVC 99, FREE=CLOSE on the DD 
statement, or the FREE option on the CLOSE macro), then the block ID for the 
next data set will not be available to your program. This is because dynamic 
unallocation frees the JFCB. 

2. When using high-speed positioning, specify the data set sequence number 


normally, either explicitly by LABEL=(seqno,SL) on the DD statement, or by 
default. 





After the system routines have used the JECRBIDO field for high-speed fe 
positioning, they clear JECRBIDO in the system’s copy of the JFCB to prevent <4 
misinterpretation during a subsequent OPEN. 
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Ensuring Data Security by Validating the Data Extent Block 





Protecting one user’s data from inadvertent or malicious access by an unauthorized 

user depends on protection of the data extent block (DEB). The DEB is a critical | 
control block because it contains information about the device a data set is | 
mounted on, and describes the location of data sets on direct access device storage ! 
volumes. The DEB also contains the address of the appendage vector table 

(AVT). Using the AVT, an unauthorized user can modify the AVT to give control 

to a routine in supervisor state to read from and write to data sets to which access 

would otherwise be denied. 


To guarantee protection of the DEB, the DEBCHK macro instruction is provided. 
The DEBCHK macro instruction can be found in SYS1.MACLIB. The DEBCHK 
macro is issued by several components of the system control program. For 
example: 


e The open access method executors issue the macro to add the address of a 
DEB they have built to a list of valid addresses called the DEB table. The 
DEB validity-checking routine builds and maintains a DEB table for each job 
step. 


« The EXCP processor uses the macro to verify that the DEB passed with each 
EXCP request is in the DEB table. 


e The close component issues the macro to remove a DEB from the DEB table. 


( - If you code a routine that builds a DEB, you must add the address of the DEB you 

built to the DEB table. If you code a routine that depends on the validity of a DEB 
that is passed to your routine, you should verify that the DEB passed to your 
routine has a valid entry in the DEB table and points to your DCB or access 
method control block (ACB). Use the TYPE=ADD and the TYPE=VERIFY 
operands of the macro, respectively. 


To prevent an asynchronous routine from changing or deleting, or assigning a new 
DEB to a DCB, you must hold the local lock. In this case, you must use the branch 
entry to the DEBCHK verify routine. 


Additional details about the functions provided by the DEB validity-checking 
routine and about the contents of the DEB table are available in Open/Close/EOV 
Logic. 


The DEBCHK macro instruction provides four functions: 


e Adds the address of a DEB to the DEB table, which is located in protected 
storage. The DEB table contains the address of every user DEB associated 
with a given job step. Every system control program component that builds a 
user DEB must add the address of that DEB to a DEB table. 


e Verifies that the DEB table associated with a given job step contains the 
address of a valid DEB and that the DEB points to the DCB (or ACB). Any 
system control program component or problem program can use this function 

C to verify that a DEB is valid. 
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e Deletes the address of a DEB from the DEB table. Any program that deletes a 
user DEB must, before it deletes the DEB, issue a DEBCHK macro with a 
TYPE=DELETE operand to delete the address of the DEB from the DEB 
table. If the DEB validity-checking routine encounters an error while deleting 
the address from the DEB table, the job step is abnormally terminated. 


e Deletes the address of a DEB from the DEB table in the same way as the 
preceding function, except that, instead of terminating the job step, this 
function merely returns an error code in register 15. This function is provided 
to prevent recurring abnormal termination. The format of the DEBCHK and a 
description of the operands follow: 


DEBCHK—Macro Specification 


[symbol] DEBCHK | cbhaddr 
|, TYPE={VERIFY | ADD | DELETE | PURGE}] 
[,AM={amtype | (amaddr) | ((amreg))}] 
[ BRANCH={NO | YES}] 


|, TCBADDR=address| 
[, KEYADDR=address| 
[.SAVREG=req] 

| MF= L] 





cbaddr 


for BRANCH=NO 
RX-type address, (2-12), or (1) 


A control block address passed to the DEBCHK routine. This operand is 
ignored if MF=L is coded. For verify, add, and delete requests, cbaddr is 
the address of a DCB or ACB that points to the DEB whose address is either 
verified to be in the DEB table, added to the DEB table, or deleted from the 
DEB table. For the purge function, cbaddr is the address of the DEB whose 
pointer is to be purged from the table: No reference is made to the DCB or 
ACB. 


Note: A spooled DCB’s DEB does not point back to the DCB, but to the 
spooled ACB; in this case, the DEBCHK should be issued against the ACB. 


for BRANCH=YES 
The A-type address of a 4-byte field, or a register (1) or (3-12), that 
points to the DCB or ACB containing the DEB to be verified. 


TYPE={VERIFY | ADD | DELETE | PURGE} 
indicates the function to be performed. If MF=L is coded, TYPE is ignored. 
The functions are: 


VERIFY 
This function is assumed if the TYPE operand is not coded. The 
control program checks the DEB table to determine whether the DEB 
pointer is in the table at the location indicated by the DEBTBLOF 
field of the DEB. The DEB is also checked to verify that 
DEBDCBAD points to the DCB (or ACB) passed to DEBCHK. The 
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| DEBAMTY? field in the DEB is compared to the AM operand value, 
( if given. The two must be equal. TYPE=VERIFY may be issued in 
% either supervisor or problem state. 


The DEB and the DCB (or ACB) must point to each other before the 
DEB address can be added to the DEB table. Before the DEB pointer 
can be added to the table, the DEB itself must be queued on the 
current TCB DEB chain (the TCBDEB field contains the address of 
the first DEB in the chain). The DEB address is added to the DEB 
table at some offset into the table. That offset value is placed in the 
DEBTBLOF field of the DEB, and the access method type is inserted 
into the DEBAMTY?P field of the DEB. A zero is placed in the | 
DEBAMTY? field if the AM operand is not coded. TYPE=ADD can : 
be issued only in supervisor state. ! 





DELETE 
The DEB and the DCB (or ACB) must point to each other before the 
DEB address can be deleted from the DEB table. TYPE=DELETE 
can be issued only in supervisor state. 





PURGE 
The DEB pointer is removed from the DEB table without checking the 
DCB (or ACB). TYPE=PURGE can be issued only in supervisor 
state. 


AM 
specifies an access method value. Each value corresponds to a particular 
access method type (note that BPAM and SAM have the same values): 





Type Value 


TCAMAP (X'84') 
SUBSYS (X'81') 


ISAM (X'80') 
BDAM (X'40') 
SAM (X'20') 
BPAM (X'20') 
TAM (X'10') 
GAM (X'08') 
TCAM (X'04') 
EXCP (X'02') 
VSAM (X'01') 
NONE (X'00') 


The operand can be coded in one of the following three ways, only the first 
of which is valid for the list form (MF=L) of the instruction. 


amtype 
refers to the access method: ISAM, BDAM, SAM, BPAM, TAM 
(which refers to BTAM only), GAM, TCAM, EXCP, or VSAM. 
TCAMAP identifies a TCAM application-program DEB. SUBSYS 
identifies a subsystem of the operating system, such as a job entry 
subsystem. NONE indicates that no access method or subsystem is 
specified. 
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(amadadr) 
is the RS-type address of the access method value. This format may 
not be coded when MF=L is used. 


((amreg)) 
is one of the general registers 1 through 14 that contains the access 
method value in its low-order byte (bit positions 24 through 31). The 
high-order bytes are not inspected. This form may not be used when 
MF=L is coded. 


The use of amaddr and amreg should be restricted to those cases where the 
access method value has been generated previously by the MF=L form of 
DEBCHK. If MF=L is not coded, the significance of the AM operand 
depends upon the TYPE. 


If TYPE is ADD and AM is specified, the access method value is inserted in 
the DEBAMTYP field of the DEB, and all subsequent DEBCHK macros 
referring to this DEB must either specify the same AM or omit the operand. 
When the AM operand is omitted for TYPE=ADD, a null value (0) is placed 
in the DEB and all subsequent DEBCHK macros must omit the AM 
operand. 


If AM is specified when the TYPE is PURGE, DELETE, or VERIFY, the 
access method value is compared to the value in the DEBAMTY?P field of 
the DEB. If AM is omitted, no comparison is made. 


BRANCH={NO | YES} | 
specifies whether you want to use the branch entry to the DEBCHK verify 
routines. 


NO 
specifies branch entry is not to be used. The operands SAVREG, 
TCBADDR, and KEYADDR are ignored. 


specifies the branch entry is to be used. TYPE=VERIFY must be 
implicitly or explicitly specified. The operands TCBADDR and 
KEYADDR are required. AM and MF are ignored. Notes for 
BRANCH= YES: 


e Registers 1, 2, 10, 11, 14, and 15 must not be used for 
SAVREG=. 


e Registers 1, 2, 10, 11, 14, 15, and the register specified for 
SAVREG= must not be used for cbaddr, TCBADDR=, or 
KEYADDRe=. 


e The contents of registers 10, 11, and 14 are unpredictable on 
completion. Also, if you do not specify SAVREG=, the contents 
of register 2 are unpredictable. 


e At completion time, register 1 contains the address of the DEB, 
and register 15 contains either 0, 4, or 16 (see “Return Codes 
from the DEBCHK Macro” on page 155 for codes and their 
meanings). 
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7 TCBADDR=address—A-type address or (3-12) 
( specifies the location or register containing the address of the TCB to be 
, used by the DEBCHK verify routine. Use this operand only when 
BRANCH. YES. 


KEY ADDR=address—A-type address or (3-12) 
specifies the location, or a register pointing to the location of a field 
containing the key to be used when accessing the DCB (or ACB). Use this 
operand only when BRANCH= YES. 


SAVREG=reg 
specifies the register in which register 2 is to be saved. Use this operand 
only when BRANCH= YES. 


MF=L 
indicates the list form of the DEBCHK macro instruction. When MF=L is 
coded, a parameter list is built consisting of the access method value that 
corresponds to the AM keyword. This value may be referenced by name in : 
another DEBCHK macro by coding AM=(amaddr), or it may be inserted ! 
into the low-order byte of a register before issuing another DEBCHK macro | 
by coding AM=((amreg)). 





Return Codes from the DEBCHK Macro 





If the DEBCHK routine completes successfully, register 15 will be set to 0 and 
register 1 will contain the address of the DEB when control is returned to your 
( program. Otherwise, register 15 will contain one of the following decimal codes: 


Code Meaning 


04(X'04') Either (a) the DEB table associated with the job step does not exist; 
or (b) the DEBTBLOF field of the DEB was set to zero or a 
negative number, or was larger than the DEB table; or (c) register 1 
did not contain the same address as the DEB table entry. 


08(X'08') An invalid TYPE was specified. (The DEBCHK routine was entered 
by a branch, not by the macro.) 


12(X'0C') Your program was not authorized and TYPE was not VERIFY. 


16(X'10') DEBDCBAD did not contain the address of the DCB (or ACB) that 
was passed to the DEBCHK routine. 


20(X'14') The AM value does not equal the value in the DEBAMTYP field. 
24(X'18') The DEB is not on the DEB chain and TYPE=ADD was specified. 


28(X'1C') TYPE=ADD was specified for a DEB that was already entered in 
the DEB table. 


32(X'20') The DEB table exceeded the maximum size (32760 bytes) and 
TYPE=ADD. 
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Purging and Restoring [I/O Requests co 


The system’s purge routines, guided by a parameter list you pass them, perform 
either a halt or a quiesce operation. In a halt operation, the purge routines stop the 
processing of specified I/O requests that were initiated with an EXCP macro 
instruction. In a quiesce operation, the purge routines: 


e Allow the completion of I/O requests that were initiated with an EXCP macro 
instruction and have been passed to the I/O supervisor for execution 


e Stop the processing of those requests that have not as yet been passed to the 
I/O supervisor, but save the IOBs of the requests so that they can be 
reprocessed (restored) later. 


The system’s restore routines make it possible to reprocess I/O requests that are 
quiesced. (Note: Not covered here is the purge and restore processing that takes in 
I/O requests not initiated by an EXCP macro instruction. If you want to learn the 
full scope of purge and restore processing, see the I/O supervisor logic section of 
System Logic Library, Volume 8.) 


You can give control to the purge and restore routines in one of two ways: (1) by 
loading register 1 with the address of the parameter list and issuing specific SVC 
instructions or (2) by issuing the PURGE and RESTORE macro instructions. If 
your installation requires the use of macro instructions, you must add the macro 
definitions to the macro library (SYS1.MACLIB) or place them in a partitioned 
data set and concatenate this data set to the macro library. The macro definitions, 
JCL, and utility statements needed to add the macros to your macro library are : 
presented in Figure 34 on page 157 and Figure 35 on page 158. Whether you “Se 
issue the macro instructions or the SVC instructions, you must first build a 

parameter list. The SVC instructions are SVC 16 for PURGE and SVC 17 for 

RESTORE. 





156 MVS/XA System—Data Administration 





( PURGE Macro Definition 





MACRO 
&SNAME PURGE §LIST 
AIF (‘&LIST* EQ. °°") .E1 
SNAME IHBINNRA &LIST LOAD REG 1 
SVC 16 
MEXIT 
E1 ITHBERMAC 01,147 LIST ADDR MISSING 
MEND 





Control Statements Required 


//jobname JOB {parameter} ) 
//stepname EXEC PGM=IEBUPDTE , PARM=NEW : 
//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYS1.MACLIB, DISP=OLD 

//SYSIN DD * 

-/ ADD NAME=PURGE, LIST=ALL 


* | 
e 
eo 


PURGE macro definition 


e 





./ ENDUP 
/* 


Figure 34. Macro Definition, JCL, and Utility Statements for Adding PURGE Macro to the 
System Macro Library 
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RESTORE Macro Definition 


MACRO 

&NAME RESTORE 6LIST 
AIF (TELIST' EO **) .B1 

SNAME IHBINNRA 6LIST LOAD REG 1 
SVC Ty ISSUE SVC FOR RESTORE 
MEXIT 

-E1 IHBERMAC 017, 150 LIST ADDR MISSING 
MEND 


Control Statements Required 


//jobname JOB {parameters} 

//stepname EXEC PGM=IEBUPDTE, PARM=NEW 
//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYS1.MACLIB,DISP=OLD 
//SYSIN DD DATA 


.-/ ADD NAME=RESTORE, LIST=ALL 
RESTORE macro definition 


./ ENDUP 
/* 


Figure 35. Macro Definition, JCL, and Utility Statements for Adding RESTORE Macro to 
the System Macro Library 


PURGE—Halt or Finish I/O-Request Processing 


The macro instruction used to call the purge routines is coded as follows: 


[symbol] PURGE parameter-list 
address 


parameter list address—-RX-type address, (2-12) or (1) 
address of a parameter list, 12 or 16 bytes long, that you have built on a 
fullword boundary in your storage. The parameter list address can be 
specified as an RX-type constant or in registers 2 through 12, or 1. 

The format and contents of the parameter list are as follows: 


Byte Contents 


0 A byte in which you specify what the purge routines will do. These are © 
the bit settings and their meanings: 


ore | Purge I/O requests to a single data set. 

















1;2;3 


5,6,7 


8 


9,10,11 


Oks sees Either purge I/O requests associated with a TCB 


or address space, or purge I/O requests to more 
than one data set. 


e peneae Post ECBs associated with purged I/O requests. 


Ps Sane Halt I/O-request processing. (Quiesce 
I/O-request processing, if 0.) 


Pr eee Purge related requests only. (Valid only if a 
data-set purge is requested.) 


Oe Reserved—must be zero. 


pees Do not purge the TCB request-block chain of 
asynchronously scheduled processing. 


ms Purge I/O requests associated with a TCB. 


lee 1 This is a 16-byte parameter list. Additional purge 
options are specified in bytes 12 to 15. (If this bit 
is off, the list is 12 bytes long, and the purge 
routines do not put a return code in byte 4 of this 
list or in register 15.) 


The address of a DEB if you are purging I/O requests to a single data 
set. The address of the first DEB in a chain of DEBs if you are 
purging I/O requests to more than one data set. (The next-to-the-last 
word of each DEB must point to the next DEB in the chain; the 
second word of the last DEB must contain zeros.) 


A byte of zeros. (If bit 7 of byte 0 is on, the purge routines will put a 
code in this byte: X'7F' if the purge operation is successful; X'40' if 
it is not successful. If bit 7 of byte 0 is off, then X'7F' appears in this 
byte.) 


The address of the TCB associated with the I/O requests you want 
purged (but only if you turned on bit 6 of byte 0). May be zeros if the 
TCB is the one you are running under. 


Driver 10. (Default value of X'00' implies that EXCP is the owner. 


The address of a word in your storage or the address of the 
DEBUSPRG field (which is X'11' bytes more than the DEB address 
in this parameter list). At whichever address you specify, the purge 
routines store a pointer to the purged I/O restore list, PIRL. In the 
PIRL is a pointer to the first IOB in the chain of IOBs. The location of 
the pointer and format of the chain are shown in Figure 36 on 

page 161. 


Note: This field is relevant for quiesce options only. 


A byte in which you can specify additional purge options. These are 
the bit settings and their meanings: 
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Note: The following applies only if bit 7 of byte O is set to one. 


sO 


13 A byte of zeros. 


Purge I/O requests associated with an address es 


space. (You must be in supervisor state.) 


Check the validity of all the DEBs associated with 
the purge operation if this is a data-set purge. 
Validate this parameter list, whatever the type of 
purge operation, by ensuring that there are no 
inconsistencies in the selection of purge options. 
(If you are in problem state, these actions are 
taken regardless of the bit setting.) 


Ensure that I/O requests will be reprocessed 
(restored) under their original TCB. (If zero, and 
this byte is meaningful (bit 7 of byte 0 is on), the 
I/O requests will be reprocessed under the TCB 
of the program making the restore request.) 


Must be zero. 


14,15 The 2-byte ID of the address space associated with the I/O requests 
you want purged. (Only meaningful if bit 2 of byte 12 is on.) 


Control is returned to your program at the instruction following the PURGE macro 


instruction. 


Return Codes from PURGE Macro 


If the purge operation was successful, register 15 will contain zeros. Otherwise, 
register 15 will contain one of the following return codes: 


Code Meaning 


04(X'04') Your request to purge I/O requests associated with a 


given TCB was not honored because that TCB did not point 
to the job step TCB, as it must when the requestor is in 
problem state. 


08(X'08') Either you requested an address-space purge operation, 


but were not in supervisor state, or you requested a 
data-set purge operation, but supplied no data-area address 
in bytes 1, 2, and 3 of the purge parameter list. 


20(X'14') Another purge request has preempted your request. You 


may want to reissue your purge request in a time-controlled 
loop. 


Note: Register 15 will contain zeros, regardless of the outcome of the purge 
operation, if you set bit 7 in byte 0 of the parameter list to zero. 
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Modifying the IOB Chain 





Note that, although this procedure is not recommended, if you want to change the 
order in which purged I/O requests are restored or prevent a purged request from 
being restored, you may change the sequence of IOBs in the IOB chain or remove 
an IOB from the chain. The address of the IOB chain can be obtained from the 
PIRL (see Figure 36). (The address of the PIRL is at the location pointed to by 
bytes 9 through 11 of the purge parameter list.) 


PIRL 






PIRRSTR 20(X'14') 






Pointer to the first I10B. If Is, 
no |/0 request was quiesced. 








>10B(1) (where 1 is first 10B in chain) 







IOBRESTR 25(19) 


: + Pointer to the next I0B in the 
chain. 
E cumeed (where n is last 10B in chain) 


|OBRESTR 25(19) 





Contains binary Ils. 


Figure 36. The PIRL and IOB Chain 





RESTORE—Reprocess I/O Requests 


The RESTORE macro is coded as follows: 


fone [RESTORE 


restore address—RX-type address, (2-12) or (1) 
address you specified at byte 9 of the purge parameter list. 
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Performing Track Calculations 


The TRKCALC macro performs track capacity calculations. The standard, list, 
execute, and DSECT forms of the macro are described. Examples of the 
TRKCALC macro follow the macro descriptions. Using TRKCALC, you may do 


the following: 


e Perform track capacity calculations 


e Determine the number of records of a given size that can be written on a full 
track or on the remainder of a track 


¢ Perform track balance calculations as follows: 


— Determine whether a given record size can be written in the space 
remaining on the track and return the new track balance. 


— Determine the maximum size record that can be written on the track if the 
given record does not fit. 


— Determine the track balance if the last physical record is removed from the 
track. 


! TRKCALC—Standard Form 


The format of the TRKCALC macro is: 


[symbol] | TRKCALC FUNCTN={TRKBAL | TRKCAP} 
{ DEVTAB=adar | ,UCB=addr | ,TYPE=addr} 
[,.BALANCE=adadr]| 
| .REMOVE=}{YES | NO}] 


| .MAXSIZE={YES | NO}] 

{,RKDD=addr | ,R=addr,K=addr,DD=addr} 
[.REGSAVE={YES | NO}] 

[.MF=]] 





FUNCTN={TRKBAL | TRKCAP} 
specifies the function to be performed. 


Note: You must specify one of the three keywords, DEVTAB, UCB, or 
TYPE, to provide the macro a source for information. 


TRKBAL 
if REMOVE=NO is specified, TRKBAL calculates whether an 
additional record fits on the track and what the new track balance 
would be if the record were added. If REMOVE= YES is specified, 
TRKBAL calculates what the track balance would be if a record were 
removed from the track. The record to be added or removed from the 
track is defined by the RKDD parameter, or by the R, K, and DD 
parameters. 
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If R=1 (or the R value in the RKDD parameter is 1) and 
REMOVE=NO is specified, record 1 is added to an empty track; if 
R=1 and REMOVE=YES is specified, record 1 is deleted from the 
track, leaving an empty track. 


If R#1, the specified record is added to or removed from the track. 
The input track balance may be supplied through the BALANCE 
parameter; if it is not supplied, it is assumed that the track contains 
equal-sized records as specified in the RKDD parameter (or in the R, 
K, and DD parameters). 


When REMOVEENDO is specified, one of the following occurs: 


e If the record fits on the track, register 0 contains the new track 
balance. 


e If the record does not fit on the track and MAXSIZE=NO is 
specified, a “record does not fit” return code is given in register 
15. 


e If the record does not fit and MAXSIZE=YES is specified, one of 
the following happens: 


— The data length of the largest record that fits in the remaining 
space is returned in register 0. 


— A code is returned that indicates no record fits in the 
remaining space. 


When REMOVE= YES is specified, one of the following occurs: 
e If R=1, register 0 contains the track capacity. 


¢ If R¥#1, registers 0 contains the input track balance (supplied 
through the BALANCE parameter) incremented by the track 
balance used by the input record. If the input balance is not 
supplied, register 0 contains the track capacity left after R—1 
records are written on the track. 


TRKCAP 
calculates, and returns in register 0, the number of fixed-length 
records that may be written on a whole track (R=1) or on a partially 
filled track (R#1). The records are defined by the K and DD values 
of the RKDD parameter, or by the K and DD parameters. 


One of the following occurs: 


e If R=1, the BALANCE parameter is ignored and the calculation 
is made on an empty track. 


e If R¥#1 and the BALANCE parameter is omitted, the calculation 
is made for a track that already contains R—1 records of the 
length defined by the K and DD values. 
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e If R#1 and the BALANCE parameter is supplied, the calculation 
is made for a track whose remaining track balance is the value of 
the BALANCE parameter. 


DEVTAB=addr—RX-type address, (2-12), (0), (14) 
addr specifies a word that contains the address of the device characteristics 
table entry (DCTE). If you specify a register, it contains the address of the 
DCTE, not the address of a word containing the address of the DCTE. The 
address of the DCTE can be found in the DCBDVTBA field of an opened 
DCB. | 


UCB=addr—RX-type address, (2-12), (0), (14) 
addr specifies the address of a word that contains the address of the UCB. If 
you specify a register, it contains the address of the UCB, not the address of 
a word containing the address of the UCB. You must ensure that the UCB 
address is valid by verifying that byte 3 (UCB+2) in the UCB contains 
X'FF', 


TYPE=addr—RX-type address, (2-12), (0), (14) 
you may specify the address of the UCB device type (UCBTBYT4), or you 
may specify the 1-byte UCB device type in the low-order byte of a register. 


BALANCE=addr—RX-type address, (2-12), (0), (14) 
you may specify either the address of a halfword containing the current track 
balance, or you may specify the balance in the low-order two bytes of a 
register. The value supplied may be the value returned when you last issued 
TRKCALC. If R=1, the balance is reset to track capacity by TRKCALC, 
and your supplied value is ignored. This is an input value and is not modified 
by the TRKCALC macro. The resulting track balance is returned in register 
0 and in the TRKCALC parameter list field STARBAL. 


REMOVE=3YES | NO} 
indicates if a record is to be deleted from the track. 


YES 
specifies that the record identified by the record number (specified in 
the R keyword) is being deleted from the track. The track balance is 
incremented instead of decremented. 


Note: YES is valid only on a FUNCTN=TRKBAL call. 
NO 
specifies that a record is not to be deleted from the track. NO is the 
default. 
MAXSIZE={YES | NO} 
YES 
If the specified record does not fit, the largest length of a record with 


the specified key length that fits is returned (register 0). 


Note: YES is valid only on a FUNCTN=TRKBAL call. 


164 MVS/XA System—Data Administration 


NO 
Maximum size is not returned. NO is the default. 





RKDD=addr—RX-type address, (2-12), (0), (14) 
addr specifies a word containing a record number (1 byte), keylength (1 
byte), and data length (2 bytes) (bytes 0, 1, and 2 and 3, respectively) or a 
register containing the record number, key length, and data length. R, K, 
and DD may be specified by this keyword, or you may use the following 
three keywords instead. 


R=addr—RX-type address, (2-12), (0), (14), orn 
you may specify either the address of the record number, or you may specify 
the record number using the low-order byte of a register or immediate data 
(n). Specify a decimal digit for n (immediate data). 


K=addr—RX-type address, (2-12), (0), (14), orn 
you may specify either the address of a field containing the hexadecimal 
value of the record’s key length, or you may specify the record’s key length 
using the low-order byte of a register or immediate data (n). Specify a 
decimal digit for n (immediate data). 


DD=addr—RX-type address, (2-12), (0), (14), orn 
you may specify either the address of a field containing the hexadecimal 
value of the record’s data length, or you may specify the record’s data length 
using the low-order two bytes of a register or immediate data (n). Specify a 
decimal digit for n (immediate data). 


( REGSAVE={YES | NO} 


YES 
specifies registers 1 through 14 are saved and restored in the 
caller-provided save area (pointed to by register 13) across the 
TRKCALC call. Otherwise, registers 1, 9, 10, 11, and 14 are 
modified. Registers 0 and 15 are always modified by a TRKCALC 


call. 
NO 
specifies registers are not saved across a TRKCALC call. NO is the 
default. 
MF=I 


specifies storage definition for the TRKCALC parameter list and parameter 
list initialization, using the given keywords, then calling the TRKCALC 
function. MF=I is the default. 


TRKCALC—Execute Form 


A remote parameter list is referred to and can be modified by the execute form of 
the TRKCALC macro. The TRKCALC routine is called. The description of the 
standard form of the macro provides the explanation of the function of each 
operand. 
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[symbol] | TRKCALC [FUNCTN={TRKBAL | TRKCAP}] — 
[{, DEVTAB={adar | *} | ee 
§UCB= addr | *t | ,.TYPE= addr | *33] 
[,BALANCE=}adar | *3] 


[.REMOVE={YES | NO}] 

[.MAXSIZE={YES | NO}] 

[i,R KDD=adar | ,R=addr,K=addr,DD=adar}]| 
‘[|,REGSAVE={YES | NO}] 

sMF=(E,addr) 





FUNCTN={TRKBAL | TRKCAP} 
is coded as shown in the standard form. If this keyword is omitted, any 
specification of REMOVE, MAXSIZE, LAST, and the RX form of 
BALANCE is ignored. In addition, DEVTAB is assumed if UCB is coded 
and a failure occurs, or if TYPE is specified. When you use FUNCTN, one 
of the keywords (DEVTAB, UCB, or TYPE) must be specified to provide an 
information source. 


DEVTAB=adadr | *—-RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the device characteristics 
table entry (DCTE) in the parameter list. 


UCB=adadr | *—RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the UCB in the oo 
parameter list. 


TYPE=addr | *—-RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the UCB type 
(UCBTYP) in the parameter list. 


BALANCE=adadr | *—RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the balance in the parameter list. 


REMOVE={YES | NO} 
is coded as shown in the standard form. 


MAXSIZE={YES | NO} 
is coded as shown in the standard form. 


RKDD=addr—RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form. 


R=addr—RX-type address, (2-12), (0), (14) orn 
is coded as shown in the standard form. 


K=addr—RX-type address, (2-12), (0), (14), orn 
is coded as shown in the standard form. 
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DD=addr—RX-type address, (2-12), (0), (14), orn 
is coded as shown in the standard form. 


REGSAVE=}YES | NO} 
is coded as shown in the standard form. 


MF=(E,addr) 
This operand specifies that the execute form of the TRKCALC macro 
instruction and an existing data management parameter list are used. 


E 
Coded as shown. 


addr——-RX-type address, (0), (1), (2-12), or (14) 
specifies an in-storage address of the parameter list. 


TRKCALC—tList Form 


The list form of the TRKCALC macro constructs an empty, in-line parameter list. 
By coding only MF=L, you construct a parameter list, and the actual values can be 
supplied by the execute form of the TRKCALC macro. Any parameters other than 
MF=L are ignored. 


[symbol] | TRKCALC MF=L 


TRKCALC—DSECT Only 


This call gives a symbolic expansion of the parameter list for the TRKCALC 
macro. No DSECT statement is generated. If a name is specified on the macro 
call, it applies, after any necessary boundary alignment, to the beginning of the list. 
The macro-generated symbols all begin with “STAR”. 


TRKCALC [MPD 


Input Register Usage for All Forms of MF 
Registers 0, 2 through 12, and 14 are available to provide input for keywords. 


Register 1 is used only to provide the address of the parameter list for an MF=E 
call. 


Register 13 may be used as input for keywords, if REGSAVE=YES is not 
specified. 


Register 15 is used as a work register to build the TRKCALC parameter list for the 
MF=E call; it is not available as an input register. 
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Output from TRKCALC 
FUNCTN=TRKBAL 


Register 15=0 3 
The record fits on the track. Register 0 and STARBAL contain the 
new track balance. 


Register 15=4 
Record does not fit on the track. If MAXSIZE=YES is specified, a 
partial record does not fit either. Register 0 and STARBAL are set to 
Zero. 


Register 15=8 
Record does not fit on the track. MAXSIZE=YES is specified, and a 
partial record does fit. Register 0 and STARBAL are set to the 
maximum number of data bytes that fit on the remainder of the track 
with the specified keylength. 


Note: The keylength is excluded from the count of maximum data 
bytes. 


STARBAL 
This is the track balance field of the TRKCALC parameter list. This 
field is first set to the track capacity if R=1, or to the supplied 
BALANCE value if R#1, or to the calculated balance if R41 and 
BALANCE are omitted. STARBAL is updated to the new track 
balance if the record fits; otherwise, STARBAL is left with the input 
track balance value. 


FUNCTN=TRKCAP 


Register 15=0 
Register 0 contains the number of records that fit on the track if R = 
1, or the number of records that fit on the remainder of the track if R 


~ 1. 


Register 15=4 
No records of the length specified fit on a full track (R = 1) ora 
partial track (R ¥ 1). Register 0 is set to zero. 


STARBAL 
This is the track balance field of the TRKCALC parameter list. This 
field is first set to the track capacity if R=1, or to the supplied 
BALANCE value if R41, or to the calculated balance if R¥1 and 
BALANCE are omitted. 
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Return Codes from TRKCALC 


The TRKCALC macro passes a return code in register 15. The return codes and 
their meanings are as follows: 


Contents Meaning 
00(X’00’) Indicates that register 0 contains the new track balance 
04(X’04’) Indicates that the record did not fit (register 0 = 0) 


08(X’08’) Indicates that the record did not fit (Register 0 contains the maximum 
data length that does fit) 


TRKCALC Macro Examples 


In this example, TRKCAL-C is coded to determine how many records of a given 
size with 10-byte keys fit on an IBM 3380 track. After issuing the macro, the 
number of records is saved in NUMREC: 


TRKCALC FUNCTN=TRKCAP, TYPE=UTYPE, R=1,K=10,DD=DL,MF=(E, (1) ) 
ST 0, NUMREC SAVE NUMBER OF RECORDS 


DL DC H'xxxx' DATA LENGTH 


UTYPE DC X'OE' 
NUMREC DS F MAX # OF RECORDS 


In this example, TRKCALC is coded to determine whether another record can fit 
on a track of a 3380, given a track balance. 


TRKCALC FUNCTN=TRKBAL, TYPE=UTYPE,R=REC,K=KL,DD=DD, BALANCE=BAL 
MAXSIZE=YES ,MF=(E, (1) ) 


UTYPE DC X'OE' 


REC DC xxx 
KL DC X'xx'! 
DD DC H'xxxx' 
BAL DC H'xxxx' 


, 
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Releasing Unused Space from a DASD Data Set 


The PARTREL Macro 


Direct Access Device Storage Management (DADSM) supports the release of we 
unused space that is allocated to sequential or partitioned data sets.* This partial 
release function is called when: 
e The data set is closed (if the RLSE subparameter of SPACE was specified on 
its DD card). 
« A restart is processing from a checkpoint in which the data set was extended 
after a checkpoint. 
e APARTREL macro is issued. 
The PARTREL macro builds a parameter list and issues a LOAD, BASSM, 
DELETE sequence. This sequence partially releases the space allocated to a data 
set without an associated OPEN/CLOSE. 
The PARTREL macro supports sequential and partitioned data sets on volumes 
with or without an indexed VTOC. The macro may be coded in the execute, 
DSECT, and list forms, but not the standard form. The calling program: 
e Must be APF authorized. 
sk 
e Must have allocated the volume to this task and must ensure it stays mounted 7 
during the PARTREL function. : 
e Must ensure that the data set is not open. 
e Must not hold any locks. 
e Must provide the address of an available standard register save area in general 
register 13. 
e Must provide the associated parameter list and parameters in storage below 16 
megabytes virtual. 
« May be in any storage key. 
e May run in either supervisor or problem program state. 
e May include the CVAFTBL mapping macro ICVAFPRM, and test the 
CVFDFPFT field. If the CVFPREL bit is on, PARTREL is supported as 
described. 
{~ 
4 The format-1 DSCB for the data set contains an identifier (DS1LSTAR) for the last . ae 


data record written. 
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PARTREL—Execute Form 





The execute form of the PARTREL macro is as follows: 


[symbol] | PARTREL | MF=({(E,addr) | (E,(reg))} 
[,DSN= {addr | (reg))}] 
| | .ERASE={YES | NO | TEST}] 


[.MODE={PGM | SUP}] 
| [,TIOT={ENQ | NOENQ}] 
[,UCB = (reg)] 





Except for MODE, all parameters default to the current contents of the parameter 
list. The MODE parameter defaults to PGM. 


To provide a better understanding of these parameters, their descriptions include 
information about DADSM execution-time processing. These descriptions use the 
term “‘effective value” to designate the value used by DADSM for this request. 
The effective value may be: 


e Specified as a parameter on the PARTREL macro. 
e Provided as the parameter’s associated value in the parameter list. 
e Defined by DADSM from the information provided in the request. 


MF={(E,addr) | (E,(reg))} 
specifies the execute form of the macro and the address of an existing 
PARTREL parameter list. 


| ( addr—RX-type address, (reg) —(0-12) 
specifies the PARTREL parameter list address. 


DSN= {addr | (reg))} 
specifies the address of a 44-byte area that contains the data set name. The 


data set name must be left-justified, with any unused bytes defined as 
blanks. 


addr—RX-type address, (reg) —(0), (2-12) 
You must provide an effective value for DSN. 


ERASE={YES | NO | TEST}] 
specifies a residual data erase attribute (see ““Deleting a Data Set from the 
VTOC (SCRATCH and CAMLST SCRATCH)” on page 33 for a 
description of erase attributes). ERASE=YES and ERASE=NO are 
mutually exclusive. The default is ERASE=TEST. 


| ERASE=YES 
| specifies that the area being released should be erased (overwritten 
| with zeros) before it is made available for new allocations. 


| ERASE=NO 
| specifies that the area should not be erased. This specification 
| overrides and RACF erase attribute. 
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ERASE=TEST 
specifies that the associated RACF erase attribute is to be used. 


MODE={PGM | SUP} 
specifies that PARTREL is requested by a caller in problem program state 
(MODE=PGM) or in supervisor state (MODE=SUP). MODE=PGM is the 
default. 


If the calling program is in supervisor state (and wants to be returned in 
supervisor state), the effective value of MODE must be SUP. If the calling 
program is in problem program state, the effective value of MODE must be 
PGM. 


TIOT={ENQ | NOENQ}] 
specifies the desired SYSZTIOT and SYSDSN ENQ processing within partial 
release. The default is ENQ. 


TIOT=ENQ 
specifies that partial release is to do its normal, exclusive ENQ on 
SYSZTIOT and SYSDSN. If either of these ENQ requests fails, 
PARTREL will terminate the request with a return code of X'08'. 


TIOT=NOENQ 
specifies that the caller has provided the necessary serialization. If 
partial release finds that the caller does not have exclusive use of 
SYSDSN, PARTREL will terminate the request with a return code of 
X'08'. 
UCB=(reg) 
specifies the address of the UCB for the volume on which the subject data 


set resides. The volume must be mounted, and you must ensure that it 
remains mounted. 


(reg)—(0), (2-12) 


You must provide an effective value for the UCB parameter. 


PARTREL—List Form 


The list form of PARTREL is specified as follows: 


[symbol] | PARTREL | MF=L 
[.DSN=addr]| 


[| ,ERASE={YES | NO | TEST}] 
[,.MODE={PGM | SUP}] 
[,TIOT={ENQ | NOENQ}] 
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Notes: 
( 1. The execute form of the UCB parameter can not be specified on the list form. 
2. The list form MODE parameter is for documentation only. The effective value of 
MODE is as specified or defaulted on the execute form. 
For an explanation of the parameters, see the execute form. 


An example of the list form’s expansion is: 


PRELPL PARTREL MF=L 


+PRELPL DS OF 

+ DC CL4'PREL' EBCDIC 'PREL' FOR PARTREL 

+ DC AL2 (PRL1E-PRELPL) LENGTH OF PARAMETER LIST 

+ DC H'O'! ERROR CODE RETURNED FROM 

+* PARTIAL RELEASE 

+ DC XL1'0OO' PARAMETER FLAG BYTE 

+ DC ¥E3:" 00" RESERVED 

+ DC A(0O) ADDRESS OF DATA SET NAME 

+ DC A(0O) UCB POINTER 

+PRLIE EQU * END OF PARAMETER LIST 
PARTREL—DSECT Form 


The DSECT form of PARTREL is specified as follows: 


( 


An example of the DSECT form’s expansion is: 


PRELPL PARTREL MF=D 


+PRELPL DSECT DSECT FOR PARAMETER LIST 
+PRLPLID DS CL4 EBCDIC 'PREL' FOR PARTREL 
+PRLNGTH DS AL2 LENGTH OF PARAMETER LIST 
+PRERRCDE DS H ERROR CODE RETURNED FROM 
+* PARTIAL RELEASE 
+PRLFLAG DS XL1 PARAMETER FLAG BYTE 
+PRLPGM EQU- x'OO'! MODE=PGM (PROBLEM PROGRAM) 
+PRLSUP EQU- xX'80' MODE=SUP (SUPERVISOR STATE) 

| +PRLTIOT EQU  xX'4O' TIOT=NOENQ 

| +PRLNERAS EQU  X'20' ERASE=NO 

| +PRLERASE EQU xX'10' _ ERASE=YES 

| +PRLFRES EQU- xX'OF' RESERVED 
+PRLRSVD DS XL3 RESERVED 
+PRLDSN ODS A DATA SET NAME POINTER 
+PRLUCB ODS A UCB POINTER 
+PRLEND EQU- ¥* END OF PARAMETER LIST 
+PRLENGTH EQU PRLEND-PRELPL LENGTH OF PARAMETER LIST 
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Return Codes From PARTREL 





Control returns to the instruction following the last instruction generated by the 
PARTREL macro. If the data set was successfully processed, register 15 contains 
zeros. Otherwise, register 15 contains one of the following return codes. This is a 
cumulative list of DADSM partial release return codes. Some of these codes may 
not apply to the PARTREL macro. 


Code 
02(X'02') 
04(X'04') 


08(X'08') 


. 


12(X'0C') 


16(X'10') 


20(X'14') 
24(X'18') 
28(X'1C') 


32(X'20') 


Meaning 
Unable to find extent in format-1 DSCB. 
Unable to find extent in format-3 DSCB. 


Either the required SYSZTIOT or SYSDSN ENQ failed, or an 
unrelated DEB indicates that another DCB is open to the data set. 


Invalid parameter list. 


Permanent I/O error or unexpected CVAF error return code or. 
installation exit rejected the request. 


DSN, or DSN pointer is invalid. 
Invalid UCB pointer. 
Given DSORG is not supported. 


No room in the VTOC. 


Allocating a DASD Data Set 


The REALLOC macro builds a parameter list and issues an SVC 32 to allocate a 
new data set. You can code the macro in the execute, DSECT, and list forms, but 
not in the standard form. The calling program: 


e Must be APF authorized. 


e Must have allocated the volume to this task and must ensure it will stay 
mounted during the REALLOC function. 


e Must not hold any locks. 


« Must provide the associated parameter list and parameters in storage below 
16-megabyte virtual. 


e May use any storage key. 


e May run in either supervisor or problem program state. 
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e Must note that REALLOC does not call RACF or catalog management. 


e May include the CVAFTBL mapping macro ICVAFPRM, and test the 
CVFDFPFT field: 


— If the CVFPREL bit is on, REALLOC is supported as it is documented in 
this release. 


— If the CVFPREL bit is off and the CVFREALL bit is on, REALLOC is 
supported as documented in a prior release. (Absolute allocation is not 
supported.) 


— If neither bit is on, REALLOC is not supported. | 


The calling program must provide the REALLOC macro with one or more model 
DSCBs. You can use the OBTAIN macro to get the DSCBs from other data sets 
and modify them for the request. DADSM uses these model DSCBs to validate the 
allocation request, and to construct those DSCBs that are written to the VTOC for 
the requested allocation. 


The ALLOC parameter for the REALLOC macro defines the allocation request as 
either absolute (ABS) or movable> (MOV). 


An absolute request provides a set of allocation parameters, a full format-1 DSCB, 
an optional format-2 DSCB, and an optional format-3 DSCB that describe the 
attributes of the desired data set: 


e« Support is provided for data sets with a user label extent and for ISAM data set 
allocations,® but is not limited to these two types. 


e The number of extents to be allocated, and their absolute placement on the 
volume, are defined by the format-1 DSCB and one (optional) format-3 
DSCB. 


An absolute request is limited to a single volume with indexed VTOC support. 


A movable request provides a set of allocation parameters and a partial DSCB’ that 
describe the attributes of the desired data set: 


e Data sets with a user label extent, ISAM data sets, and absolute track allocated 
data sets are not supported. 


5 The requested data set’s allocation is not sensitive to its placement on the volume. 
This is specifically NOT a reference to the format-1 DSCB bit DS1DSGU (unmovable 
bit), which may be either on or off in an ALLOC=MOV request’s partial DSCB. That 
is, the data set may subsequently contain location-dependent information. 


6 See the description of the F2DSCB parameter in the REALLOC macro execute form 
for more information. 


7 The partial DSCB (mapped by the IECPDSCB macro) consists of the first 98 bytes of 


a format-1 DSCB followed by two full words: PDPRIQTY (primary space request in 
tracks), and PDDIRQTY (number of directory blocks). 
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e The maximum number of extents that may be allocated is determined by the 7 
data set organization (PD1DSORG) and the data set indicator (PD1DSIND) f ~ 
bytes in the partial DSCB. If PD1DSORG indicates a VSAM data set ‘Ly 
organization and PD1DSIND indicates that the data set is cataloged in an 
Integrated Catalog Facility catalog, the maximum number of extents is 123. 

Otherwise, the maximum number of extents is 16. 


A movable request is limited to a single volume with or without indexed VTOC 
support. 


REALLOC—Execute Form 


The format of the REALLOC macro in execute form is: 


[symbol] | REALLOC | MF={(E,addr) | (E,(reg))} 
{, ALLOC={ABS | MOV}?} 
[,DSSIZE={adadr | (reg)}] 
[,.F2DSCB=$adar | (reg)}] 


[,.F3DSCB={adadr | (reg)}] 
[| MINAU=fadar | (reg)}] 
[,PDSCB= addr | (reg)}] 
[|,PDSDIR=$adadr | (reg)}] 
[,UCB=(reg)] 





All parameters except ALLOC default to the current contents of the referenced ; 
parameter list. The ALLOC parameter defaults to MOV. —_, 


To provide a better understanding of this macro’s parameters, their descriptions 
include information about DADSM execution-time processing. These descriptions 
use the term “‘effective value” to designate the value used by DADSM for this 
request. The effective value may be: 


e Specified as a parameter for the REALLOC macro. 
e Provided as the parameter’s associated value in the referenced parameter list. 
e Defined by DADSM from information provided in the request. 


MF={(E,adar | (E,(reg))} 
specifies the execute form of the macro and the address of a REALLOC 
parameter list. 


addr—RX-type address, (reg)—(0-12) 
specifies the address of the REALLOC parameter list. 


ALLOC={ABS | MOV} 
specifies that the REALLOC request is for absolute extents 
(ALLOC=ABS) or for a movable allocation (ALLOC=MOV). 
ALLOC=MOV is the default. 


If you want absolute allocation, the effective value of ALLOC must be ABS. 
DSSIZE= {addr | (reg)} 


specifies the size of the data set to be allocated in tracks. The DSSIZE 
parameter is invalid for an ALLOC=ABS request. 
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addr—RX-type address 
( | specifies the address of a full word that contains the data set size. 


(reg)—(0), (2-12) 
specifies a register that contains the size of the data set. 


You must provide an effective value for DSSIZE for an ALLOC=MOV 
request. The PDPRIQTY field of the partial DSCB is ignored. 


DADSM assumes that you have provided the effective value of DSSIZE in 
tracks even if the PDI1SCALO flag byte of the partial DSCB indicates a 
cylinder request, X'CO', or an average block request, X'40'. 


If the PDISCALO flag byte of the partial DSCB indicates a cylinder request, 
X'CO', or an average block with round request, X'41', the effective value of 
DSSIZE is rounded up to the next full cylinder. 


F2DSCB= {addr | (reg)} 
specifies the in-storage address of a format-2 DSCB. This DSCB is used as 
a model to construct the allocated data set’s format-2 DSCB. 


The F2DSCB parameter is invalid for an ALLOC=MOV request. 


addr—RX-~-type address, (reg)—(0), (2-12) 


he You may provide an effective value for F2ZDSCB in an ALLOC=ABS 
( . request when the DS1DSORG flag byte of the given format-1 DSCB is 
A X'80' (indexed sequential organization). 


Because REALLOC allocates on the basis of a single volume for each 
request and because a multivolume ISAM data set is defined with one 
format-2 DSCB (on the first volume only), the associated DADSM 
allocation processing routines do not require a format-2 DSCB (that is, 
multiple REALLOC requests may be used to to allocate a multivolume 
ISAM data set). 


F3DSCB= {addr | (reg)} 
specifies the in-storage address of a format-3 DSCB. This DSCB is used as 
a model to construct the allocated data set’s format-3 DSCB. 


The F3DSCB parameter is invalid for an ALLOC=MOV request. 


addr—RX-type address, (reg) —(0), (2-12) 


You must provide an effective value for F3DSCB in an ALLOC=ABS 
request when the DSINOEPV byte of the format-1 DSCB indicates more 
than three extents (or when the DS1NOEPV byte indicates more than two 
extents and the DSIEXT1 extent type indicator is X'40'; a user label 
extent). 


The REALLOC request is limited to a maximum of 16 extents. No more 
than one format-3 DSCB can be specified. 





Chapter 6. System Macro Instructions 177 











You must provide an effective value of zero for the F3DSCB in an 
ALLOC=ABS request when the DS1NOEPV byte of the format-1 DSCB 
indicates that there are less than four extents (or when the DS1NOEPV byte 
indicates that there are less than three extents and the DSIEXT1 extent type 
indicator is X'40'; a user label extent). 


_ 


& 3 
a 


MINAU={adar | (reg)} 
specifies the size of the minimum allocation unit in tracks. All primary 
extents for this data set are in multiples of this minimum allocation unit. 
This minimum does not apply to subsequent extensions of the data set. 


The MINAU parameter is invalid on an ALLOC=ABS request. 


addr—RX-type address 
specifies the address of a full word containing the minimum allocation 
unit. 


(reg)—(0), (2-12) 


specifies a register containing the minimum allocation unit. 
The MINAU parameter has no effect on the requested allocation if: 


e You provide an effective value of zero. 
e The PD1ISCALO flag byte of the partial DSCB indicates either a 
cylinder request, X'CO', or an average block with round request, X'41'. 
Otherwise, the effective value of DSSIZE must be a multiple of the effective 
value of MINAU. Gos 


PDSCB=3addr | (reg)} 
specifies the address of a partial DSCB (for ALLOC=MOV) or the 
in-storage address of a full format-1 DSCB (for ALLOC=ABS). This 
DSCB is used as a model to construct the allocated data set’s format-1 
DSCB. 


addr—-RX-type address, (reg) —(0), (2-12) 


You must provide an effective value for the PDSCB parameter. 


PDSDIR= {addr | (reg)} 
specifies the number of 256-byte directory blocks for a partitioned data set 
(PDS). 


addr—RX-type address 
specifies an in-storage address of a full word containing the number of 
256-byte PDS directory blocks. 


(reg)—(0), (2-12) 
specifies a register containing the number of 256-byte PDS directory 
blocks. 


You must provide an effective value for PDSDIR when partitioned 
organization is indicated: 
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e The DSIDSORG flag byte of the format-1 DSCB is X'02! 
(ALLOC=ABS). 

e The PD1DSORG flag byte of the partial DSCB is X'02' 
(ALLOC=MOV). 





For an ALLOC=MOV request, you can specify the effective value of 
PDSDIR in the PDDIRQTY field of the partial DSCB. The PDDIROTY 
field is used if and only if, the effective REALLOC parameter list value of 
PDSDIR is zero. 


Do not specify an effective value for PDSDIR when a PDS is not indicated. 
UCB=(reg) 

specifies the address of the UCB for the volume in which the data set is to be 

allocated. The volume must be mounted, and you must ensure that it 


remains mounted. 


(reg)—(0), (2-12) 


You must provide an effective value for the UCB parameter. 


REALLOC—List Form 


The list form of the REALLOC macro is specified as follows: 


( [symbol] | REALLOC | MF=L 
[ ALLOC={ABS | MOV}] 


[,F2DSCB=adadr] 
[,F3DSCB=adar]| 
|,.PDSCB=adadr] 





Notes: 


1. The execute form parameters DSSIZE, MINAU, PDSDIR, and UCB can not be 
specified on the list form. 


2. The list form’s ALLOC parameter affects the tests made by the REALLOC 
macro at assembly time and the contents of the parameter list. 


3. The effective value of ALLOC is as specified or defaulted on the execute form. 
See the execute form for an explanation of the parameters. 


An example of the list form expansion is: 
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REALPL 
+REALPL 


% 


++tteteetterertt 


+ 
5 
z 
es 


REALLOC—DSECT Only 


REALLOC MF=L | 


DS 
DC 
DC 
DC 


DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
EQU 


OF 

CL4'REAL' 

AL2 (RAL1E-REALPL) 
H'O' 


XL1'0OO' 
XL3'00' 


F'o! 


F'O' 
A(0) 
A (0) 
F'O!' 
A (0) 
A(0) 
* 





EBCDIC 'REAL' FOR REALLOC 
LENGTH OF PARAMETER LIST 
ERROR CODE RETURNED FROM 
ALLOCATE (SVC 32) 
PARAMETER FLAG BYTE 
RESERVED 
DATA SET SIZE 
MINIMUM ALLOCATION UNIT 
PARTIAL DSCB POINTER 
UCB POINTER 
PDS DIRECTORY QUANTITY 
FORMAT 2 DSCB POINTER 
FORMAT 3 DSCB POINTER 
END OF PARAMETER LIST 


The DSECT form of REALLOC is specified as follows: 


[iomion [ReaLoc [MF=D SSCS 


An example of the DSECT form expansion is: 


REALPL 
+REALPL 
+RALPLID 
+RALNGTH 
+RAERRCDE 


* 


+RALFLAG 
+RALMOV 
+RALABS 
+RALFRES 
+RALRSVD 
+RALDSSZ 
+RALMAU 
+RALPDSCB 
+RALUCB 
+RALDQTY 
+RAL2DSCB 
+RAL3DSCB 
+RALEND 
+RALENGTH 


REALLOC MF=D 


DSECT 
DS 
DS 
DS 


DS 
EQU 
EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
EQU 
EQU 
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CL4 
AL2 
H 


*¥prmdrrmyy 


RALEND-REALPL 


DSECT FOR PARAMETER LIST 

EBCDIC 'REAL' FOR REALLOC 

LENGTH OF PARAMETER LIST 

ERROR CODE RETURNED FROM 
ALLOCATE (SVC 32) 

PARAMETER FLAG BYTE 

ALLOC=MOV 

ALLOC=ABS 

RESERVED 

RESERVED 

DATA SET SIZE 

MINIMUM ALLOCATION UNIT 

PARTIAL DSCB POINTER 

UCB POINTER 

PDS DIRECTORY QUANTITY 

FORMAT 2 DSCB POINTER 

FORMAT 3 DSCB POINTER 

END OF PARAMETER LIST 

LENGTH OF PARAMETER LIST 


Ne 








Return Codes from REALLOC 


Control returns to the instruction following the SVC 32 generated by the 
REALLOC macro. If the data set was successfully allocated, register 15 contains 
zeros. Otherwise, register 15 contains one of the following return codes: 


Note: This is a cumulative list of DADSM allocation return codes. Some of these 
codes may not apply to the REALLOC macro. 


Return 
Code (R15) 


004(X'04"') 


008(X'08') 


012(X'0C') 


016(X'10') 
020(X'14') 
024(X'18') 


028(X'1C') 


~ 032(X'20') 


036(X'24') 


040(X'28') 


044(X'2C') 


| 048(X'30') 


Reason 
‘Code (RO) 


01(X'01') 
02(X'02') 


03(X'03') 


Meaning 

Data set name of request already exists on this 
volume. Initial allocation not possible under the 
name given. 

No room available in the WTOC or VTOC index. 
One of the following errors was encountered: 

e Permanent I/O error 

e Error returned by CVAF 

Requested absolute track not available. 
Requested quantity not available. 


Average record length greater than 65535 bytes. 


Incorrect DSORG or DISP in an ISAM index 
request. 


No prime area requested for ISAM data set. 


ISAM prime area must be requested before 
overflow. 


Space requested must begin on a cylinder 
boundary. 


Duplicate ISAM DSNAME element. 
Invalid REALLOC parmlist ID. 
Invalid REALLOC parmlist length. 


REALLOC request, but neither ALLOC=ABS nor 
ALLOC=MOV is specified. 
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Return 
Code (R15) 


052(X'34') 


056(X'38') 


060(X'3C') 


064(X'40') 
068(X'44') 
072(X'48') 


076(X'4C') 


080(X'50') 
084(X'54"') 
088(X'58') 
092(X'5C') 
096(X'60') 
100(X'64"') 
104(X'68') 


108(X'6C') 


112(X'70') 
116(X'74') 


120(X'78') 
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Reason 
Code (RO) 


04(X'04"') 
05(X'05') 
06(X'06') 


07(X'07') 


_ Meaning 


Invalid data set size specified for ALLOC=MOV. 
The data set is not a PDS for an ALLOC=MOV. 
The data set is not a PDS for an ALLOC=ABS. 


No directory quantity specified for a PDS for an 
ALLOC=ABS. | 


Invalid JFCB or partial DSCB pointer. 


Requested directory space is larger than the space 
available on this volume. | 


Nonindexed VTOC not supported for REALLOC 
ALLOC=ABS request. 


Invalid user label request. 
Invalid UCB pointer. 
DOS VTOC cannot be converted to an OS VTOC. 


No space parameter given for a new data set or 
zero space requested at absolute track zero. 


Invalid request for ISAM index. 

ISAM multivolume index not allowed. 

Invalid ISAM DSNAME element. 

ISAM multivolume overflow request not allowed. 
ABSTR and CYL requests conflict. 

CYL and CONTIG requests conflict. 

Invalid space subparameter. 


Primary space request for an ISAM data set is zero, 
or primary space for an ABSTR request is zero. 


Duplicate ISAM index request. 
User labels not supported. 


Invalid combination of values for DSSIZE and 
MINAU. 











Return 
Code (R15) 


124(X'7C') 


128(X'80') 


132(X'84') 
136(X'88') 
140(X'8C') 


144(X'90') 


148(X'94') 


152(X'98') 


156(X'9C') 


160(X'A0') 


164(X'A4"') 


168(X'A8') 


172(X'AC') 


176(X'BO') 


180(X'B4') 


184(X'B8') 


188(X'BC') 


Reason 
Code (RO) 


Meaning 
DSSIZE is not a multiple of MINAU. 


Directory space requested is larger than primary 
space. 


Space request must be ABSTR for DOS volume. 
Invalid F3DSCB pointer. 
ISAM index must be requested before prime area. 


Last concatenated DD card unnecessary or invalid 
for this ISAM data set. 


Overlapping extents in the VTOC. 


Overlapping DOS split cylinder extents in the 
VTOC. 


DADSM allocation terminated because of possible 
VTOC errors. 


ISAM allocation terminated because of possible 
VTOC errors. 


Allocation terminated because of DOS stacked 
pack format. 


RACF define failed, data set profile already 
defined. 


User not authorized to define data set. 
Installation exit rejected this request with a return 
code of 8. No further volumes should be 
attempted. 

Installation exit rejected this request with a return 
code of 4. For a nonspecific volume request, 


another volume may be attempted. 


RACF define with modeling specified and model 
not found. 


Invalid F2DSCB pointer. 
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Message Displays on the IBM 3480 Magnetic Tape Subsystem co 


The MSGDISP macro displays a message on the IBM 3480. With MSGDISP, you 
can specify the message to be displayed and how to display it (for example, steady 
or flashing). The six main parameters of the macro and their functions are: 
MOUNT Displays an “‘M”’ in position 1 of the display area during a mount 


request until a volume is loaded and made ready. The “‘M”’ is 
followed by the volume serial number and label type. 


VERIFY Shows that a volume has been accepted by displaying its serial 
number and label type in positions 2 through 8. 


RDY Displays text in positions 2 through 7 while a data set is open. 


DEMOUNT Displays a volume disposition indicator in position 1 until a volume is 
demounted. 


RESET Clears the display area. 


GEN Provides the full range of display options, including the option to 
alternate two messages. 


All except the RDY parameter require that you be in supervisor state, have a 
storage protect key of 0 through 7, or be authorized by the authorized program 
facility. 

For MVS/XA, you may specify the IOSLEVEL (priority) of the request with the Nee 
FORCE parameter. IOSLEVEL support replaces single-level I/O quiescing with 

multilevel quiescing; the higher the IOSLEVEL value, the greater your priority to 

control the device. 

The MSGDISP macro generates a parameter list as input to an SVC routine. 


- MSGDISP may be coded in the standard, execute, and list forms. 


The formats for specifying MSGDISP with the six main parameters, and the return 
codes generated by MSGDISP, are given in the sections that follow. 


MSGDISP—Displaying a Mount Message 


The format for specifying MSGDISP with the MOUNT parameter is: 


ae MSGDISP | MOUNT 
»UCB=(reg) 
[,.FORCE={NO | YES | 2 | keyword | (reg)}] 
[| LABEL={'A'|'N'|'S'| 'X"' | addr}] 


[.MF={L | (E,addr)}] 

[,.SER={'volser' | addr] 

[,TEST={NO | YES}] oe 
[, WAIT={NO | YES}] qf 





184 MVS/XA System—Data Administration 











MOUNT 
displays an ‘‘M”’ in position 1 of the display area during a mount request. 
The ‘*M”’ is followed by a volume serial number and label type. The display 
flashes on and off until a volume is loaded and ready. If the device is ready 
at the time a mount request is issued, the “‘M”’ is not displayed. 


UCB=(reg)—(2-12) 
specifies a register containing the UCB address for the device. 


FORCE={NO | YES | 2 | keyword | (reg)} 


specifies the priority (IOSLEVEL) for the display request’s I/O. The higher 
the IOSLEVEL value, the greater the priority. 


If you do not specify the FORCE parameter, the default is FORCE=NO. 








NO 
prevents execution of a display request for a device whose I/O is 
being quiesced. The IOSLEVEL is set to the installation default, as 
indicated in the CVTIONLYV field of the CVT. 

YES | 
forces execution of a display request for a device even if its I/O is 
being quiesced. The IOSLEVEL is set to 9, the highest priority. 

n 
specifies a decimal number from 1 to 9, to be used as the IOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 

keyword 
specifies a label equated to an IOSLEVEL value: 

NORMAL 1 
QUIESCE 2 
DAVV 3 
DDR 4 
DYNPATH 5 
UNCRSV 6 
CHPRCVY 7 
SCHRCVY 8 
FDEV 9 
(reg) 


specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the IOSLEVEL. 


LABEL=}'A'|'N'|'S|'X' | addr} 
displays the label type of the mounted volume in position 8. If you specify 
an unknown label type other than a blank, a ‘‘?”’ is displayed. 


tA! 


specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user labels 
(AUL). Specify in apostrophes. 
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specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 


specifies IBM Standard (SL) or IBM Standard with user labels (SUL). 
Specify in apostrophes. 


specifies nonstandard labels (NSL). Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing an “‘A’’, ““N”’, 
“*S’’, or ‘“X”’ (see the following explanations of these characters). For 
MF=L, you may only specify an A-type address. 


MF=3L | (E,addr)} 
specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

(E,addr) 


specifies that the execute form of the macro and an existing parameter 
list are used. 


addr—RX-type address, (1), or (2-12) 
specifies an in-storage address of the parameter list. 


SER=}' volser' | addr} 
specifies the serial number of the volume to be mounted. The serial number 
is displayed in positions 2 through 7. If you do not specify SER, the system 
supplies the volume serial number. If the serial number is not available, a 
scratch volume is used, unless the volume use attribute indicates a default of 
“PRIVAT”’. 


"yolser' 
specifies the volume serial number as a literal. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial number. For 
MF=L, you may only specify an A-type address. 


TEST={NO | YES} : 
specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 


NO 
specifies that the SVC routine will test the UCB. 
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AY 


ae 





YES 
specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB mapping macro 
(IEFUCBOB) in the source code. 


WAIT={NO | YES} 
specifies when control is returned to you. 


NO 
specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 

YES 


specifies that control is to be returned after I/O is complete. 


MSGDISP—Displaying a Verify Message 


The format for specifying MSGDISP with the VERIFY parameter is: 


symbol| | MSGDISP| VERIFY 
»UCB=(reg) 
|. FORCE={NO | YES | » | keyword | (reg)}] 
[ LABEL={'A'|'N'|'S' | 'X' | addrt] 


[.MF={L | (E,addr)}] 
[,SER=$'volser' | addr}] 
[, TEST={NO | YES}] 
[, WAIT={NO | YES}] 





VERIFY 
displays the serial number and label type of a volume that has been accepted 
in positions 2 through 8. Position 1 remains blank. The display lasts until 
the next display request is executed. 


UCB=(reg)—(2-12) 
specifies a register containing the UCB address for the device. 


FORCE=[NO | YES | n | keyword | (reg)} 
specifies the priority (IOSLEVEL) for the display request’s I/O. The higher 
the IOSLEVEL value, the greater the priority. 


If you do not specify the FORCE parameter, the default is FORCE=NO. 


NO 
prevents execution of a display request for a device whose I/O is 
being quiesced. The IOSLEVEL is set to the installation default, as 
indicated in the CVTIONLYV field of the CVT. 

YES 


forces execution of a display request for a device even if its I/O is 
being quiesced. The IOSLEVEL is set to 9, the highest priority. 
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specifies a decimal number from 1 to 9, to be used as the IOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 


keyword 
specifies a label equated to an IOSLEVEL value: 


NORMAL 
QUIESCE 
DAVV 
DDR 
DYNPATH 
UNCRSV 
CHPRCVY 
SCHRCVY 
FDEV 


OANA NA PWN 


(reg) 
specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the IOSLEVEL. 


LABEL=}'A'|'N'|'S'|' | addr} 
specifies label type of the mounted volume in position 8 of the display. If an 
unknown label type other than a blank is specified, a ‘‘?” is displayed. 


i] A! 
specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user (AUL) 
labels. Specify in apostrophes. 


specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 


specifies IBM Standard (SL) or IBM Standard with user (SUL) labels. 
Specify in apostrophes. 


specifies nonstandard (NSL) labels. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing an “‘A’’, “N”’, 
*“S’’, or ““X’’ (see explanations below for these characters). For 
MF=L, you may only specify an A-type address. 


MF=}L | (E,addr)} 
specifies either the execute or list form of MSGDISP. If you do not specify 
this parameter, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 
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(E,addr) 
specifies that the execute form of the macro and an existing parameter 
list is to be used. 





addr—RX-type address, (1), or (2-12) 
specifies an in-storage address of the parameter list. 


SER=$' volser' | addr} 
specifies the serial number of the volume that has been verified. The serial 
number displays in positions 2 through 7. If you do not specify SER, the 
system supplies the volume serial number. If the serial number is not 
available, a scratch volume is used, unless the volume use attribute indicates 
a default of ““PRIVAT”’. 


'volser' 
specifies the volume serial number as a literal. Specify in apostrophes. 





addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial number. For 
MF=L, you may only specify an A-type address. 


TEST={NO | YES} 
specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 





NO 
( i specifies that the SVC routine will test the UCB. 


YES 
specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB mapping macro 
(IEFUCBOB) in the source code. 


WAIT={NO | YES} 
specifies when control is to be returned to you. 


NO 
specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 

YES 


specifies that control is to be returned after I/O is complete. 


MSGDISP—Displaying a Ready Message 


The format for specifying MSGDISP with the RDY parameter is: 


[symbol] | MSGDISP | RDY 
»DCB=addr 





[.MF={L | (E,addr)}] 
[,TXT={'msgtxt' | addr | 
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RDY we 


displays the text supplied in the TXT parameter in positions 2 through 7 aa 
while the data set is open. The display is steady (not flashing) and is A 
enclosed in parentheses. The display is also written to the tape pool console 

(routing code 3, descriptor code 7). 


DCB=addr 
specifies the address of a DCB opened to a data set on the mounted volume. 
If multiple devices are allocated, the message display is directed to the one 
containing the volume currently in use. 


Note: If multiple devices or multiple volumes are allocated, you may update 
a message display after an end-of-volume condition by using the EOV exit 
specified in a DCB exit list. In the case of a concatenated data set with . 
unlike characteristics, the DCB OPEN exit may be used to update the 
display. 


addr—-RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the opened DCB. For MF=L, you 
may only specify an A-type address. 


MF=3L | (E,addr)} 
specifies either the execute or list form of MSGDISP. If this parameter is not 
specified, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can —_ 
modify the parameter list. 

(E,addr) 


specifies that the execute form of the macro and an existing parameter 
list is to be used. 


addr—RX-type address, (1), or (2-12) 
specifies an in-storage address of the parameter list. 


TXT=}' msegtxt' | addr} 
specifies up to six characters to display in positions 2 through 7 of the 
display. If you do not specify TXT, blanks are displayed. 


'"msgtxt' 
specifies the text as a literal. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing the text to be 
displayed. For MF=L, you may only specify an A-type address. 
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MSGDISP—Displaying a Demount Message 





The format for specifying MSGDISP with the DEMOUNT parameter is: 


[symbol] | MSGDISP | DEMOUNT 
JUCB=(reg) 
[LDISP={'D' | 'K'| 'R' | addr}] 
[| FORCE={NO | YES | 2 | keyword | (reg)}] 
[MF={L | (E,addr)}] 


| .MLABEL=}'A'|'N']'S' | 'X! | addr}] 
[ MSER=§$'volser-to-mount' | addr}] 

[ SER={'volser' | addr}] 

[,TEST={NO | YES}] 

[,WAIT={NO | YES}] 





DEMOUNT 
Displays a volume disposition indicator in position 1 until the volume is 
demounted. Optionally, you may display the serial number of the volume to 
be demounted at the same time. The display flashes on and off. If a volume 
is not mounted on the device when the display request is executed, blanks 
are displayed. 








The demount message may be displayed alternately (flashing) with a mount 
message for the next volume by specifying the MSER parameter. 


( — UCB=(reg)—(2-12) 
| specifies a register containing the UCB address for the device. 


DISP=$'D' | 'K' | 'R' | addr} 
specifies the character to display in position 1, representing the volume 
disposition. 


'p! 
Demount a public volume. Specify in apostrophes. 


Note: ‘“D” also displays when you specify an invalid character or 
when the volume use attribute is unknown (as in an automatic volume 
recognition (AVR) error when reading a label). 


Keep a private volume and return it to the library. Specify in 
apostrophes. 


Retain a private volume near the device for further use. Specify in 
apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing a ““D”’, “K’’, or 
“R”. For MF=L, you may only specify an A-type address. 





FORCE={NO | YES | n | keyword | (reg)} 
specifies the priority (IOSLEVEL) for the display request’s I/O. The higher 
the IOSLEVEL value, the greater the priority. 
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If you do not specify the FORCE parameter, the default is FORCE=NO. 


NO 
prevents execution of a display request for a device whose I/O is 
being quiesced. The IOSLEVEL is set to the installation default, as 
indicated in the CVTIONLYV field of the CVT. 
YES 
forces execution of a display request for a device even if its I/O is 
being quiesced. The IOSLEVEL is set to 9, the highest priority. 
n 
specifies a decimal number from 1 to 9, to be used as the IOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 
keyword 
specifies a label equated to an IOSLEVEL value: 
NORMAL 1 
QUIESCE 2 
DAVV 3 
DDR 4 
DYNPATH 5 
UNCRSV 6 
CHPRCVY 7 
SCHRCVY 8 
FDEV 9 
(reg) 


specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the IOSLEVEL. 


MF=3L | (E,addr)} 
specifies either the execute or list form of MSGDISP. If you do not specify 
this parameter, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

(E,addr) 


specifies that the execute form of the macro and an existing parameter 
list is to be used. 


addr—-RX-type address, (1), or (2-12) 
specifies an in-storage address of the parameter list. 


MLABEL=3$'A'|'N' | 'S'| 'X' | addr} 
displays the label type of the volume to be loaded and made ready following 
a demount, in position 8. If you specify an unknown label type other than a 
blank, a “‘?”’ is displayed. You may only specify this parameter if you also 
specify the MSER parameter. 
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specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user (AUL) 
labels. Specify in apostrophes. 





'N'I 
specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 

1 S! 
specifies IBM Standard (SL) or IBM Standard with user (SUL) labels. 
Specify in apostrophes. 

'X! 


specifies nonstandard (NSL) labels. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing an “‘A”’, ““N’’, 
““S”’, or “X” (see the following explanations of these characters). For 
MF=L, you may only specify an A-type address. 





MSER=$' volser-to-mount' | addr} 
displays the mount message for the next volume alternately (flashing) with 
the demount message. The display continues untilyou demount the current 
volume. At that time, the mount message will display (flashing) until you 
load the volume and make the device ready. If no volume is mounted at the 
time the demount and mount messages are executed, only the mount 
( i message will display (flashing) until the volume is loaded and ready. 


'yolser-to-mount' 
specifies the volume serial number of the volume to be mounted, as a 
literal. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial number of the 
volume to be mounted. For MF=L, you may only specify an A-type 
address. 


SER=}' volser' | addr} 
specifies the serial number of the volume to be demounted. The serial 
number is displayed in positions 2 through 7. If you do not specify SER, the 
system supplies the volume serial number. If the serial number is not 
available, a scratch volume is used, unless the volume use attribute indicates 
a default of ‘““PRIVAT”’. 


'volser' 
specifies the volume serial number as a literal. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial number. This 
parameter is not valid for the MF=L form. For MF=L, you may only 
specify an A-type address. 


TEST={NO | YES} 
specifies whether to test the UCB to determine if the device is capable of 
displaying messages. message display SVC routine. 
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specifies that the SVC routine will test the UCB. 





specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB mapping macro 
(TEFUCBOB) in the source code. 


WAIT={NO | YES} 
specifies when control is to be returned to you. 


NO 
specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 

YES 


specifies that control is to be returned after I/O is complete. 


MSGDISP—Resetting the Message Display 


The format for specifying MSGDISP with the RESET parameter is: 


[symbol] | MSGDISP | RESET 
tUCB=(reg) |, UCBL=addr} - 
[,FORCE={NO | YES | | keyword | (reg)}] wees 


[.MF= iL | (E,addr)}] 
[, TEST={NO | YES}] 
[,WAIT={NO | YES}] 





RESET 
clears all existing data on the display. If you specify WAIT=NO and the last 
service requested was a demount, the display is not cleared. 


After being cleared, the display will show the device’s internal status message 
(for example, a message indicating that the device is ready). 


UCB=(reg)—(2-12) 
specifies a register containing the UCB address for the device. 


UCBL=addr—RX-type address, A-type address, (0), or (2-12) 
specifies the address of a list containing a maximum of 64 words. Each word 
in the list contains the address of a UCB representing a device whose display 
is to be reset. The end of the list is indicated by a '1' in the high order bit of 
the last address in the list. If an error is encountered while processing the 
list, register 1 points to the associated UCB when you regain control. 


You cannot specify UCBL with TEST=YES and WAIT=NO. 
FORCE={NO | YES | 2 | keyword | (reg)} 


specifies the priority (IOSLEVEL) for the display request’s I/O. The higher 
the IOSLEVEL value, the greater the priority. 
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If you do not specify the FORCE parameter, the default is FORCE=NO. 








NO 
prevents execution of a display request for a device whose I/O is 
being quiesced. The IOSLEVEL is set to the installation default, as 
indicated in the CVTIONLYV field of the CVT. 
YES 
forces execution of a display request for a device even if its I/O is 
being quiesced. The IOSLEVEL is set to 9, the highest priority. 
n 
specifies a decimal number from 1 to 9, to be used as the IOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 
keyword 
specifies a label equated to an IOSLEVEL value: 
NORMAL 1 
QUIESCE 2 
DAVV 3 
DDR 4 
DYNPATH 5 
UNCRSV 6 
CHPRCVY 7 
SCHRCVY 8 
FDEV 9 
(reg) 


specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the IOSLEVEL. 


MF={L | (E,addr)} 
specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

(E,addr) 


specifies that the execute form of the macro and an existing parameter 
list is to be used. | 


addr—RX-type address, (1), or (2-12) 
specifies the address of the parameter list. 


TEST={NO | YES} 


specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 
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specifies that the SVC routine will test the UCB. 

YES 
specifies testing the UCB before the SVC call. You cannot specify 
TEST=YES if you also specify the UCBL parameter. 


Note: TEST=YES requires you to include the UCB mapping macro 
(IEFUCBOB) in the source code. 


WAIT={NO | YES} 
specifies when control is to be returned to you. 


NO 
specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 
You cannot specify WAIT=NO if you also specify the UCBL 
parameter. 


specifies that control is to be returned after I/O is complete. 


Note: Demount messages can be reset only if WAIT=YES is 
specified. i 


“Nia a 
Ri geet 
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MSGDISP—Providing the Full Range of Display Options 


The format for specifying MSGDISP with the GEN parameter is: 


[symbol] | MSGDISP | GEN 
»UCB=(reg) 
| .FLASH={STEADY | STEADY2 
| BLINK | BLINK2 | ALT}] 
[| FORCE={NO | YES | | keyword | (reg)}] 


|L.MF={L | (E,addr i] 

[,TEST={NO | YES}] 

|, TXT=${'msgtxt' | addr] 

[,TXT2=$'altmsgtxt' | addr}] 

[| .VOL={STATIC | REMOVE | INSERT | SWAP}] 
[,WAIT={NO | YES}] 





GEN 
specifies the full range of display options. 


UCB=(reg)—(2-12) 
specifies a register containing the UCB address for the device. 


FLASH={STEADY | STEADY2 | BLINK | BLINK2 | ALT} 
specifies message display mode. 


Note: If you specify VOL=SWAP, messages will always be displayed as if 
you had specified FLASH=ALT 


STEADY 


specifies that the primary message (TXT) is to be displayed without 
flashing. 


STEADY2 


specifies that the alternate message (TXT2) is to be displayed without 
flashing. 


BLINK 
specifies that the primary message (TXT) flash on and off at a rate of 
approximately two seconds on and one-half second off. 


BLINK2 
specifies that the alternate message (TXT2) flash on and off at a rate 
of approximately two seconds on and one-half second off. 


ALT 
specifies that the primary and alternate messages (TXT and TXT2) 
flash on and off alternately, at a rate of approximately two seconds on 
and one-half second off. 


FORCE=${NO | YES | n | keyword | (reg)} 
specifies the priority IOSLEVEL) for the display request’s I/O. The higher 
the IOSLEVEL value, the greater the priority. 


If you do not specify the FORCE parameter, the default is FORCE=NO. 
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prevents execution of a display request for a device whose I/O is A 
being quiesced. The IOSLEVEL is set to the installation default, as Woy 
indicated in the CVTIONLV field of the CVT. 


forces execution of a display request for a device even if its I/O is 
being quiesced. The IOSLEVEL is set to 9, the highest priority. 


specifies a decimal number from 1 to 9, to be used as the IOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 


keyword 
specifies a label equated to an IOSLEVEL value: 


NORMAL 1 
QUIESCE 2 
DAVV 3 
DDR 4 
DYNPATH 5 
UNCRSV_ 6 
CHPRCVY 7 
SCHRCVY 8 
FDEV 9 


(reg) 
specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the IOSLEVEL. 


MF=L | (E,addr)} 
specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 


L 
specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

(E,addr) 


specifies that the execute form of the macro and an existing parameter 
list is to be used. 


addr 
specifies an in-storage address of the parameter list. Specify 


either an RX-type address or a register in the range of 2 
through 12. 


TEST={NO | YES} 
specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 
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( specifies that the SVC routine will test the UCB. 


specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB mapping macro 
(IEFUCBOB) in the source code. 


TXT={' msgtxt' | addr} 
specifies 8 characters to be shown in positions 1 through 8 of the display. If 
you do not specify TXT, blanks are displayed. 


"msgtxt' : 
specifies the 8 characters as literals. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing the 8 characters. 
For MF=L, you may only specify an A-type address. 


TXT2=$'altmsgtxt' | addr} 
specifies 8 alternate characters to display in positions 1 through 8 of the 
display. If you do not specify TXT2, blanks are displayed. 


‘altmsgtxt' 
specifies the 8 characters as literals. Specify in apostrophes. 


( - addr—RX-type address, A-type address, or (2-12) 
—_ 9 specifies an in-storage address of an area containing the 8 characters. 
For MF=L, you may only specify an A-type address. 


VOL={STATIC | REMOVE | INSERT | SWAP} 
specifies message display mode, based on volume status. 


STATIC 
specifies that messages will display without regard to volume status 
until the next message request is executed, or until the next command 
initiates volume movement. 


REMOVE 
specifies that messages will display until the current volume is 
demounted. This parameter is ignored if a volume is not mounted 
when the request is executed. 


INSERT 
specifies that messages will display until a volume is present, the tape 
threaded, and the active/inactive switch is in the active position. This 
parameter is ignored if a volume is loaded and ready when the request 
is executed. 


SWAP 
specifies that messages will always display as if FLASH=ALT were 
gas specified. The data from TXT and TXT2 displays alternately 
( (flashing) until the current volume has been demounted. Then only 
TXT2 will display (flashing) until a new volume is loaded and ready. 
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If no volume is mounted when this parameter is specified, only TXT2 
data will display (flashing) until a new volume is loaded and ready. 


WAIT={NO | YES} 
specifies when control is to be returned to you. 


NO 
specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 
YES 
specifies that control is to be returned after I/O is complete. 
Return Codes from MSGDISP 








When the system returns control to the problem program, the low-order byte of | 
register 15 contains a return code. The low-order byte of register 0 may contain a 
reason code as follows: 


Return Reason 
Code (R15) Code (RO) Meaning 
00(X'00') Successful completion. 
04(X'04') Device does not support MSGDISP. 
O8(X'08') Unauthorized request (failed TESTAUTH for 
proper authority level) or invalid input parameters 
(including DCB or UCB). 
08(X'08') 01(X'O1"') Invalid parameter. 
02(X'02') Invalid DCB or DEBCHK error. 
03(X'03') Environmental error. 
04(X'04') Authorization violation. 
05(X'05') Invalid UCB. 
06(X'06') Invalid request. 
11(X'OB') Unsuccessful ESTAE macro call. 
12(X'0C') Unsuccessful GETMAIN request. 
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LO 


Return Reason 
Code (R15) Code (RO) Meaning 





12(X'0C') I/O error (I/O Supervisor posted the request for 
an error). 


Note: AnI/O error occurs for load display if the 
drive display has a hardware failure. 


If you get return code X'04' or X'O0C' on a RESET UCBL operation, register 1 
points to the UCB associated with the error when you regain control. 
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This chapter describes how to maintain the system image library 
(SYS1.IMAGELIB) and UCS images for the IBM 1403, 3203, and 3211 Printers, 
and FCB images for the IBM 3203, 3211, and 4245 Printers. Sample JCL 
jobstreams for adding a UCS image to SYS1.IMAGELIB for the IBM 1403, 3203, 
and 3211 Printers are shown in Figure 37 on page 206, Figure 38 on page 207, 
and Figure 39 on page 208, respectively. 


SYS1.IMAGELIB does not contain UCS images for the IBM 3262 Model 5, 4245, 
or 4248 Printers, but instead contains image tables. By means of these image 
tables, the system relates the user-requested UCS image to the corresponding print 
band. Figure 40 on page 210 defines and describes the structure of an image 
table entry. The contents of IBM-supplied image tables for the IBM 4245 and 
4248 Printers are shown in Figure 41 on page 211 and Figure 42 on page 212, 
respectively. The IBM 3262 Model 5 Printer uses the same image table as the 
4248. 


This chapter also describes How to maintain the UCS image table in 
SYS1.IMAGELIB for the IBM 3262 Model 5, 4245, and 4248 Printers. To 
determine which print bands are available, see: 


e IBM 3262 Printer Model 5 Product Description, containing information on 
band IDs for the 3262 Model 5 Printer 


e IBM 4245 Printer Model 1 Component Description and Operator’s Guide, 
containing information on band IDs for the 4245 Printer 


e IBM 4248 Printer Description, containing information on band IDs for the 
4248 Printer 


SYS1.IMAGELIJB also contains control modules for the IBM 3800 Printing 
Subsystem. You can use the IEBIMAGE utility program to create and maintain 
these control modules (character arrangement table modules, graphic character 
modification modules, copy modification modules, library character set modules, 
and FCB modules). 


You can also use IEBIMAGE to create and maintain FCB modules in 
SYS1.IMAGELIB for the 4248 Printer. You can use FCB modules created for the 
4248 with the 3262 Model 5 Printer. However, the 3262 Model 5 does not 
support variable printer speeds or the horizontal copy feature of the 4248. For 
more information about IEBIMAGE, see Utilities. 


This chapter also describes how to retrieve an FCB image from SYS1 .IMAGELIB 
for modification. 
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To use the information presented in this chapter, you should be familiar with the 
subjects of the following publications: 


e Data Administration: Macro Instruction Reference describes the SETPRT macro 
that you can use to specify the images or modules that you want. 


e JCL Reference describes the CHARS, MODIFY, UCB, and FCB parameters 
of the DD statement that are processed at OPEN time. 


e IBM 2821 Control Unit Component Description contains information on 
creating a user-designed chain/train for the 1403 Printer. 


e IBM 3203 Printer Component Description and Operator’s Guide contains 
information on creating a user-designed train for the 3203 Printer. 


e IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer 
Control Unit Component Description and Operator’s Guide contains information 
on creating a user-designed train for the 3211 Printer. 


e JES2 Initialization and Tuning and Network Job Entry Facility for JES2 contain 
reference information for JES2. 


¢ JES3 Initialization and Tuning 


You can use the SPZAP service aid to display and modify an existing member of 
SYS1.IMAGELIB. Service Aids describes the use of SPZAP. 


UCS Images in SYS1.IMAGELIB 


Most IBM standard character set images are included in SYS1.IMAGELIB at 
system generation time, through the DATAMGT macro and an IODEVICE macro 
for the specified printer. (For details on the DATAMGT and IODEVICE macros, 
see System Generation.) The standard character set images for the 1403, 3203, and 
3211 Printers are shown below. 


[Par [mages 


1403 or 3203 AN, HN, PCAN, PCHN, PN, QNC, ON, RN, SN, TN, 








XN, YN 


3211 A111, G11, H11, P11, T11 





Adding a UCS Image to the Image Library 


Using the assembler and linkage editor, you may add a UCS image to those that 
reside in SYS1.IMAGELIB. No executable code is generated; the assembler 
prepares DCs, and the linkage editor puts them into SYS1.IMAGELIB. The new 
UCS image must be structured according to the following rules: 


1. The member name must be 5 to 8 characters long; the first 4 characters must 
be the appropriate UCS prefix, as shown below. 
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UCS1 - 1403 Printer 
UCS2 - 3211 Printer (or 3211-compatible printer) 
UCS3 - 3203 Printer 


These first four characters must be followed by a character set code, one to 
four characters long. Any valid combination of letters and numbers under 
assembler language rules is acceptable. However, the single letters U or C 
must not be used, because they are symbols for special conditions recognized 
by the system. The assigned character set code must be specified on the DD 
statement or SETPRT macro to load the image into the UCS buffer. 


You can supply an alias name for a new image with the ALIAS statement of 
the linkage editor. (For more information on the ALIAS statement, see 
Linkage Editor and Loader User’s Guide.) 


The first byte of the character set image load module specifies whether the 
image is a default. (Default images may be used by the system for jobs that do 
not request a specific image.) Specify the following in the first byte: 
For JES2: 

X'80' indicates a default image. 

X'40' indicates that the output is to be folded. 

X'CO' indicates default image and folding. 

X'00' indicates that the image is not to be used as a default. 
For non-JES2: 

X'80' indicates a default image. 

X'00' indicates that the image is not to be used as a default. 
The second byte of the load module indicates the number of lines (n) to be 
printed for image verification. See ‘‘Verifying the UCS Image” on page 215 
for more information on image verification. 
Each byte of the next n bytes indicates the number of characters to be printed 
on each verification line. For the 3211 Printer, the maximum number of 
characters printed per line is 48; the bytes of associative bits (see note 5) are 
not printed during verification. 
The UCS image itself must follow the previously described fields. The image 
must fill the number of bytes required by the printer; see the table below for 
image lengths. Note that, because of Assembler language syntax, two 


apostrophes or two ampersands must be coded to represent a single apostrophe 
or a single ampersand, respectively, within a character set image. 
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[Pieter [age ovat 
1403 240 bytes 


3203 304 bytes (240 characters followed by 64 bytes of 
associative bits) 





3211 | 512 bytes (432 characters followed by 15 bytes of X'00' 
64 bytes of associative bits, and one reserved byte of 
X'00') 


Associative bits must be coded to prevent data checks when adding a UCS 
image to SYS1.IMAGELIB. See the appropriate printer manual for more 
information on coding associative bits. 


UCS Coding Examples 
e Figure 37 contains an example of adding a 1403 UCS image, YN, to 
SYS1.IMAGELIB or the image library. Notes follow Figure 39 on page 208. 
e Figure 38 on page 207 shows the code used to add a 3203 UCS image, YN, 
to SYS1.IMAGELIB or the image library. 
e Figure 39 on page 208 shows the code used to add a 3211 UCS image, A11, 
to SYS1.IMAGELIB or the image library. 
//ADDYN JOB MSGLEVEL=1 
//STEP EXEC PROC=ASMFCL, PARM.ASM='NODECK,LOAD', 


PARM. LKED='LIST,OL,REFR,RENT, XREF' 
//ASM.SYSIN DD * 
UCS1YN CSECT 


DC X'80' (THIS IS A DEFAULT IMAGE) 

DC AL 1 (6) (NUMBER OF LINES TO BE PRINTED) 

DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1 (42) (42 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1 (42) (42 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 6) 

* THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 


DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, . 


' 

DC C'1234567890STABCDEFGHIJKLMNOPOQRSTUVWXYZ*, .#-$' 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .' 
DC C' 1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, . : 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .#-$' 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*,.' 
END 

/* 

//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS1YN) ,DISP=OLD, 

// SPACE= (OVERRIDE SECONDARY ALLOCATION) 


Figure 37. Sample Code to Add a 1403 UCS Image to SYS1.[MAGELIB 
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//ADYN3203 JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL,PARM.ASM='"NODECK,LOAD', 
pay PARM. LKED='LIST,OL,REFR, RENT, XREF' 
//BSM.SYSIN DD * 

UCS3YN  CSECT 





DC X'80' (THIS IS A DEFAULT IMAGE) 

DC AL 1 (6) (NUMBER OF LINES TO BE PRINTED) 

DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1 (42) (42 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL 1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL 1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1 (42) (42 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1 (39) (39 CHARACTERS TO BE PRINTED ON LINE 6) 

* THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 


DC C'1234567890STABCDEFGHIJKLMNOPQORSTUVWXYZ*, .' 


DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .#-$' 
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*, .' 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .' 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .#-$' 
DC C'1234567890STABCDEFGHIJKLMNOPORSTUVWXYZ*, .' 
* THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 
* UCSB BYTE POSITIONS 241-304 
DC X'CO1010101010101010100040000000000010' 
DC X'101010101010101000404000000040001010' 
DC X'101010101010004000000000101010101010' 
DC X'101010100040000000008' 
END 
ff * 
//GKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS3YN) ,DISP=OLD, 
Vee SPACE= (OVERRIDE SECONDARY ALLOCATION) 
( Figure 38. Sample Code to Add a 3203 UCS Image to SYS1.IMAGELIB 
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//ADDA11 JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL, PARM.ASM="NODECK,LOAD', 
// PARM. LKED='LIST,OL,REFR, RENT, XREF' 
//ASM.SYSIN DD * 

UCS2A11  CSECT 





DC X'80' (THIS IS A DEFAULT IMAGE) 

DC AL1 (9) (NUMBER OF LINES TO BE PRINTED) 

DC AL (48) (48 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL (48) (48 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL 1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL 1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 6) 
DC AL1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 7) 
DC AL 1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 8) 
DC AL1 (48) (48 CHARACTERS TO BE PRINTED ON LINE 9) 


* 


THE FOLLOWING NINE LINES REPRESENT THE TRAIN IMAGE 

NOTE 2 AMPERSANDS MUST BE CODED TO GET 1 IN ASSEMBLER SYNTAX 
DC C'1<.+IHGFEDCBA* $-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJ&%, &&ZYXWVUTS/0#098765432' 
DC C'1<,.+IHGFEDCBA* $—-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJ 4%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA*$—-RQPONMLKJ&% , &&ZYXWVUTS/0#098765432' 
DC C'1<.+IHGFEDCBA* $-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC 15X'OO' (RESERVED FIELD, BYTES 433-447) 

* THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 

UCSB BYTE POSITIONS 448-511 | 
DC X¥'CO01010101010101010100040404240004010' - 
DC X¥'101010101010101000404041000040401010' . 
DC X'101010101010004040000000101010101010' - 
DC X'10101010004040444800' 


* 


* 


DC X'OO' (RESERVED FIELD, BYTE 512) 
END 
/* 
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS2A11) ,DISP=OLD, 
J/ SPACE= (OVERRIDE SECONDARY ALLOCATION) 


Figure 39. Sample Code to Add a 3211 UCS Image to SYS1.IMAGELIB 
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Notes to Figure 37 on page 206, Figure 38 on page 207, and Figure 39: 





| 1. The RENT and REFR linkage editor attributes are required. 


2. For the 3203 and 3211 Printers, the 64 bytes of associative bits must be coded 
to avoid data checks. To determine how to code these bits for a particular 
image, see [BM 3203 Printer Component Description and Operator’s Guide or 
IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer 
Control Unit Component Description and Operator’s Guide. 


3. Executing the ASMFCL procedure does not actually generate executable code. 
The assembler/linkage editor merely places the UCS image into 
SYS1.IMAGELIB. 


4. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. By eliminating the override you 
can use the original secondary allocation amount. 


UCS Image Tables in SYS1.IMAGELIB 


SYS1.IMAGELIB does not contain UCS images for the IBM 3262 Model 5, 4245, 
or 4248 Printers, but contains image tables. The UCS image for each band is 
stored, instead, in the printer, and is automatically loaded into the UCS buffer 
when the machine is powered on or a new band is installed. See Figure 40 on 
page 210 for the format of image table entries, and ““Adding or Modifying a UCS 
Image Table Entry” on page 213 for information on how to add or modify an 
image table entry. 





SYS1.IMAGELIB contains one UCS image table for each type of printer that 
supports image tables. An image table contains an entry for most 
installation-standard IBM-supplied bands. The 4245 image table is named UCSS. 
The shared 4248 and 3262 Model 5 image table is named UCS6. 


Alias Names in Image Tables 


The image tables also define alias names for most installation-standard print bands 
used on the IBM 4245 and 4248 Printers. The IBM-supplied image tables do not 
provide alias names for the IBM 3262 Model 5 Printer. 


Some print chains/trains/bands, such as SN and KA22, do not have alias names 
because there is no equivalent chain/train/band on other printers. You can assign 
an alias for these chains/trains with the linkage editor ALIAS statement. (For 
more information on the ALIAS statement, see Linkage Editor and Loader User’s 
Guide.) For the 3262 Model 5, 4245, or 4248 Printer, you can add an alias name 
by adding or modifying an entry in the UCS image table. See ‘Adding or 
Modifying a UCS Image Table Entry” on page 213. A typical UCS image table 
entry is shown in Figure 40 on page 210. | 
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Figure 40. UCS Image Table Entry Format 





Notes to Figure 40: 


1. This field 1s optional. 


Description data’ 


Length of description data! 


Lengths of verification lines 


2 


(VLENGTH); one byte per line 


Number of verification lines 


2 


Reserved (set to zero) 


Description offset (set to zero if omitted) 


Verification offset (set to zero if omitted) 


Flag Byte: X‘00’= 
x'40'= 
X’60'= 
X'80'= 

UCS Image Name 


Non-default image 
Fold image 

Fold image/ Default 
Default image 


UCS Image Name or Alias (1-4 character 
name, left-justified and padded to a 


4-character length with blanks, if necessary) 


Length of this entry 


2. This field is optional for the 4245 Printer. For the 3262 Model 5 and the 
4248, this field does not apply and is set to X'00'. 
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The contents of the UCS image table UCS5 (IGGUCSS macro), for the 4245 
Printer, are shown in Figure 41. 


Descition 


YES Default UCS image 


|NO —_| 1403/3203 AN image 
3211 All image 


: 


wal 


; 


Nondefauli UCS image 


1403/3203 HN image 
3211 H11 image | 
4248 4101 image 
Nondefault UCS image 
1403/3203 PN image 
3211 P11 image 

4248 4121 image 
Nondefault UCS image 
4248 4201 image 
Nondefault UCS image 
1403/3203 TN image 
3211 T11 image 

4248 4181 image 
Nondefault UCS image 
3211 Gil image 

4248 41C1 image 
Nondefault UCS image 
1403/3203 RN image 


NO | 
NO 
NO 

NO | 
NO 

NO 

NO 

No. | 
NO | 
NO 
NO 

NO 

NO 

NO | 
no] 
‘NO | Nondefault UCS image 
[NO 
NO | 
NOU | 


ae 


NN 


EERE EE 


1 | PL21 
| PN 
| Pil 

| | 4121 
|S | SN21 
1SN21 | 4201 


[YES 
[NO 
4248 40E1 image 
[NO 
[NO | 
[NO 
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4248 4041 image 
Nondefault UCS image 
Nondefault UCS image 
4248 4161 image 


| KA22 
| FC21 


[roar [aici 


Figure 41. UCSS5 Image Table Contents 
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The contents of the UCS image table UCS6 (IGGUCS6 macro), for the 4248 
Printer, are shown in Figure 42. - 


Pains [Defeat [Decco 
O 
O 
N 
N 



































Z, 
: 


4101 4101 INO | Nondefault UCS image 

4101. | HN21 4245 HN21 image 

4101 |HN |NO | 1403/3203 HN image 

41C1 | 41C1 Nondefault UCS image 

41C1_ |GN21 [NO | 4245 GN21 image 
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Figure 42. UCS6 Image Table Contents 


Note: The image tables for the 4245 and 4248 Printers include USA and Canada 
band IDs only. To support other national band IDs, you must modify the UCS 
image table. See “Adding or Modifying a UCS Image Table Entry” on page 213. 


The 3262 Model 5 Printer uses the 4248 UCS image table, UCS6. However, no 
3262 Model 5 band names or aliases are provided by IBM in UCS6. In order to 
use 3262 Model 5 UCS images, you must add the names and aliases to UCS6 
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yourself. ‘‘Adding or Modifying a UCS Image Table Entry” on page 213 
describes how to add entries to the UCS image table. For a list of the bands 
available for the 3262 Model 5, see IBM 3262 Printer Model 5 Product Description. 





Adding or Modifying a UCS Image Table Entry 


If you plan to use a new UCS image name/alias with the 3262 Model 5, 4245, or 
4248 Printer, you must add an entry for that image name/alias to the appropriate 
UCS image table. As shown below, use the assembler to compile the image table 
module, then link-edit the object file into SYS1.IMAGELIB. Similarly, if you want 
to select a new default image or change the description on an old image, you must 
change the image table. 


To build new UCS table entries, or to change the format of old entries, use the 
following procedure. Also, see ““Example 1: Adding a New Band ID to the 4245 
UCS Image Table (UCSS)” on page 216 and ‘Example 2: Adding a New Default 
Entry to the 4248 UCS Image Table (UCS6).” on page 216. 


1. Issue the IGGUCSIT macro, as described below, to build a new UCS image 
table entry. If you are updating the image table as shown in the following two 
examples, the linkage editor builds a new entry at the start of the table, even if 
you intended to replace an existing entry. When the system subsequently uses 
the table, it encounters the new entry first, thus the old one is effectively 
replaced. 


2. Include the UCS image table source, using the IGGUCSS or IGGUCS6 macro, 
| ( oe both of which are found in SYS1.MACLIB. 


3. Assemble the image table module (UCSS5S or UCS6). 
4. Link-edit the assembled module into SYS1.IMAGELIB. 
Note: RENT and REFR are required attributes. 


The IGGUCSIT macro instruction has the following format: 
IGGUCSIT MF=}LIST | DSECT} 


sNAME=image name 
[,ALIAS=image alias] 


[| DEFAULT={YES | NQ}] 


[,DESCR=description]| 


[| DEVICE={4245 | 42483] 


[,VLENGTH=(n/,n2,. . .n)] 





[| FOLD={YES | NO}] 


MF={LIST | DSECT} 
specifies the form of the macro instruction. 
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LIST 
produces a UCS image table entry based on the information 
supplied in other IGGUCSIT parameters. If LIST is selected or 
allowed to default, the NAME parameter must also be coded. 


DSECT 7 
produces a DSECT for a single UCS image table entry, similar to 
the sample entry shown in Figure 40 on page 210. If you code 
DSECT, all other parameters of IGGUCSIT are ignored. 


LIST is the default. 


NAME= image name 
specifies the 1 to 4 character UCS image name. 


ALIAS=image alias 
specifies a 1 to 4 character alias name for the UCS image. If ALIAS is 
not specified, the image name coded in the NAME parameter will be 
entered in the UCS image table. 


DEFAULT=}YES | NO} 
indicates whether the new UCS image is to be used as a default value. 


YES 
indicates that this UCS image is a default. Default images are used 
by the system for jobs that do not request a specific image. 


NO 


indicates that this UCS image should not be used as a default. 


If the DEFAULT parameter is not specified, the new UCS image is not 
used as a default. 


DESCR=description 
specifies descriptive information about the new UCS image. description 
can be up to 32 EBCDIC or hexadecimal characters long. You cannot use 
EBCDIC and hexadecimal characters in combination. 


Descriptive information is placed in the header line of the verification 
display, following the real UCS image name. If you omit the DESCR 
parameter, no description appears in the display. For more information on 
the verification display, see ‘‘Verifying the UCS Image” on page 215. 


If VLENGTH is not specified for the 4245 Printer, the DESCR parameter 
is ignored. 


DEVICE={4245 | 4248} | 
specifies the type of device for which an image table entry is to be created. 


If you specify MF=LIST on the first invocation of the IGGUCSIT macro, 
DEVICE defaults to 4245. The default for subsequent invocations is the 
printer type that you specified (or the default) on the first invocation. 
Table entries with different DEVICE specifications are not allowed. 
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Verifying the UCS Image 


For the 3262 Model 5 Printer, DEVICE=4248 should be specified in 
order to create the appropriate form of the image table entry. 


VLENGTH=(n/,n2,. .. n) 
specifies the length(s) of each line in the UCS verification display. The 
length of each line must be specified separately, even if all lines are of the 
same length. 


nI is the length of print line 1; n2 is the length of print line 2; n is the 
length of the last print line. To display the complete image, the sum of the 
verification line lengths should equal 350. 


For details on the verification report, see “‘Verifying the UCS Image.” 


The VLENGTH parameter is not valid for the 3262 Model 5 or 4248 
Printer. 


FOLD={YES | NO} 
indicates whether the UCS image is to be folded. 


YES 
indicates that the UCS image is to be folded. Allows printing only 
uppercase characters from either upper- or lowercase data codes. 
Folding continues until an UNFOLD command is received. 


indicates that the UCS image is not to be folded. This is the default. 


For the 1403 (with the UCS feature), 3203, 3211, 3262 Model 5, 4245, and 
4248 Printers, you can print the UCS image for visual verification using either of 
the following parameters: 


e« InJCL: UCS=(character set code,,.VERIFY) 

e Inthe SETPRT macro: UCS=(character set code,,V) 

You can also use these parameters for the 3262 Model 5 and 4248 Printers. 
However, because the UCS image cannot be read directly from the 3262 Model 


5, or 4248, only the header information is printed. The verification display 
header appears in the format shown below. 


UCS IMAGE VERIFICATION image id [,FOLD] [description] 





image id 
The 1- to 4-character name of the UCS image. 


description 


The descriptive information supplied for this UCS image in the UCS 
image table. 
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For more information about the UCS VERIFY parameters, see JCL Reference ; 
and Data Administration: Macro Instruction Reference. (i 


Examples of Adding to the UCS Image Table 


Example 1: Adding a New Band ID to the 4245 UCS Image Table (UCS5) 


In this example, the band name RPQ1 with description '"RPQ BAND" is added 
to UCSS. In the UCS verification display, 7 lines of 50 characters each are 
printed. Macro IGGUCSS causes the UCS image table source (as distributed by 
IBM) to be included in the table entry. 


//UCS5 JOB * 

EXEC ASMFCL, 
PARM.ASM='NODECK,LOAD', 
PARM.LKED='OL,RENT,REUS' 

//SYSPRINT DD SYSOUT=A 
//ASM.SYSIN DD * 

TITLE 'UPDATED UCS5 IMAGE TABLE' 
UCS5 CSECT 

IGGUCSIT NAME=RPQ1, 
VLENGTH= (50,50,50,50,50,50,50), 
DESCR='RPQ BAND' 

IGGUCS5 

END 


{* os 
//UKED.SYSLMOD DD DSN=SYS1.IMAGELIB(UCS5) ,DISP=OLD, i 


// SPACE= (OVERRIDE SECONDARY ALLOCATION) 





Notes to Example 1: 
1. The RENT and REUS linkage editor attributes are required. 


2. Executing the ASMFCL procedure does not actually generate executable 
code. The assembler/linkage editor places the updated UCS image table 
into SYS1.IMAGELIB. | 


3. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 


Example 2: Adding a New Default Entry to the 4248 UCS Image Table (UCS6). 


In the following example, the band name 40E1 with description ''40E1 
DEFAULT BAND" is added to UCS6 and defined as a default band. An alias 
name, HN21, is also defined for band 40E1. Macro IGGUCS6 causes the UCS 
image table source (as distributed by IBM) to be included in the table entry. 
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//ucS6 JOB ... 
EXEC ASMFCL, 
// PARM.ASM='NODECK,LOAD', 
PARM.LKED='0L,RENT,REUS' 
//SYSPRINT DD SYSOUT=A 
//ASM.SYSIN DD * 
TITLE 'UPDATED UCS6 IMAGE TABLE' 
UCS6 CSECT 
IGGUCSIT NAME=40E1, 
DEVICE=4248, 
ALIAS=HN21, 
DEFAULT=YES, 
DESCR='40E1 DEFAULT BAND' 
IGGUCS6 
END 


/* 
//LKED.SYSLMOD DD DSN=SYS1.IMAGELIB(UCS6) ,DISP=OLD, 
SPACE= (OVERRIDE SECONDARY ALLOCATION) 





Notes to Example 2: 

1. This method creates a duplicate entry for 40E1 that becomes the first entry 
in the table. Because the table is searched sequentially, the new entry is 
always found before the old entry, thus effectively replacing the old entry. 

| 2. The RENT and REUS linkage editor attributes are required. 

3. Executing the ASMFCL procedure does not generate executable code. The 
assembler/linkage editor places the updated UCS image table into 
SYS1.IMAGELIB. 

4. The SPACE parameter is overridden because the ASMFCL cataloged 


procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 


FCB Images in SYS1.IMAGELIB 


Two standard FCB images, STD1 and STD2, are included in SYS1.IMAGELIB 
during system generation for the following printers: 


3203 
3211 
3262 Model 5 
4245 
4248 


The 4248 and 3262 Model 5 Printers also accept FCBs that can be used with the 
3203, 3211, and 4245 Printers. (These are referred to as 3211 format FCBs.) 
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FCB2STD1 


Figure 43. 


CSECT 


STD1 sets line spacing at 6 lines per inch for an 8-1/2 inch form; STD2 is a 
default FCB image that sets line spacing at 6 lines per inch for an 11-inch form. 
Channels for both images are evenly spaced, with Channel 1 on the fourth line 
and Channel 9 on the last line. See Figure 43 on page 218 and Figure 44 on 
page 219 for sample STD1 and STD2 images. 


The 3262 Model 5, the 4245, and the 4248 Printer each load a default FCB 
image into the buffer when they are powered on. The 3262 Model 5 default 
FCB image is an 11-inch form with 6 lines per inch, a Channel 1 on the third 
print line, and a Channel 12 on line 64. The 4245 default FCB image is an 
11-inch form with 6 lines per inch and a Channel 1 on the first print line. The 
4248 default FCB image is the last FCB image loaded. 


The standard FCB images STD3 is included in SYS1.IMAGELIB during system 
generation for the following printer: 


3800 


You should use the IEBIMAGE utility to create and modify FCB modules for 
the 3800 Printing Subsystem. You should also use it to create and modify FCB 
images for the 3262 Model 5 or 4248 Printer (4248 format FCBs). 


Note: FCB module CSECT names for the 3262 Model 5 and 4248 Printers 
must begin with the letters ““FCB4” For information on IEBIMAGE and the 
format of the 4248 FCB image, see Utilities. 


X'8o' DEFAULT 

AL1(48) FCB IMAGE LENGTH = 48 
X'000000' LINE 1, 2, 3 

X'O1' LINE 4, CHANNEL 1 
X'000000' LINE 5, 6, 7 

X'02' LINE 8, CHANNEL 2 
x'000000' LINE 9, 10, 11 
x'03' LINE 12, CHANNEL 3 
X'000000' LINE 13, 14, 15 
x'O4! LINE 16, CHANNEL 4 
X'000000' LINE 17, 18, 19 
X'05' LINE 20, CHANNEL 5 
X'000000' LINE 21, 22, 23 
x'06' LINE 24, CHANNEL 6 
X'000000' LINE 25, 26, 27 
x'07' LINE 28, CHANNEL 7 
X'000000' LINE 29, 30, 31 
x'08' LINE 32, CHANNEL 8 
X'000000" LINE 33, 34, 35 
X'OA! LINE 36, CHANNEL 10 
X'000000' LINE 37, 38, 39 
X'OB' LINE 40, CHANNEL 11 
X'000000' LINE 41, 42, 43 
x'oc! LINE 44, CHANNEL 12 
X'000000' LINE 45, 46, 47 
x'19! LINE 48, CHANNEL 9-END OF FCB IMAGE 


Sample of the Standard FCB Image STD1 
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FCB2STD2 CSECT 


DC x'80' DEFAULT 
DC AL 1 (66) FCB IMAGE LENGTH = 66 
DC X'000000' LINE 1, 2, 3 
DC xX'O1' LINE 4, CHANNEL 1 
DC X'0000000000' LINE 5, 6, 7, 8, 9 
DC X'O2' LINE 10, CHANNEL 2 
DC _X'0000000000' LINE 11, 12, 13, 14, 15 
DC Xx'O3' LINE 16, CHANNEL 3 
DC —_ X'0000000000' LINE 17, 18, 19, 20, 21 
DC X'O4' LINE 22, CHANNEL 4 
DC _ X'0000000000' LINE 23, 24, 25, 26, 27 
DC x'O5' LINE 28, CHANNEL 5 
DC _X'0000000000' LINE 29, 30, 31, 32, 33 
DC x'O6' LINE 34, CHANNEL 6 
DC _x'0000000000' LINE 35, 36, 37, 38, 39 
DC X'O7' LINE 40, CHANNEL 7 
DC _x'0000000000' LINE 41, 42, 43, 44, 45 
DC xX'08' LINE 46, CHANNEL 8 
DC _ X'0000000000' LINE 47, 48, 49, 50, 51 
DC X"OA'’ LINE 52, CHANNEL 10 
DC _X'0000000000' LINE 53, 54, 55, 56, 57 
DC X'OB' LINE 58, CHANNEL 11 
DC _x'0000000000' LINE 59, 60, 61, 62, 63 
DC x'OC' LINE 64, CHANNEL 12 
DC = x'00" LINE 65 
DC x'19' LINE 66, CHANNEL 9-END OF FCB IMAGE 
END 

( Figure 44. Sample of the Standard FCB Image STD2 


Adding an FCB Image to the Image Library 


You may add a 3211-format FCB image to those that reside in 
SYS1.IMAGELIB, using the assembler and linkage editor. No executable code 
is generated; the assembler prepares DCs, and the linkage editor links them into 
SYS1.IMAGELIB. The new FCB image must be structured according to the 
following rules: 


1. The member name may not exceed eight bytes. The first four characters of 
the name must be FCB2. The characters that follow identify the FCB image 
and are referred to as the "image identifier" (ID). Any combination of valid 
assembler language characters can be used, with the exception of a single 
“C” or “U,” because these are used by the system to recognize special _ 
conditions. The image identifier must be specified in the FCB keyword of a 
DD statement or in the SETPRT macro to load the image into the FCB 
buffer. 


2. The first byte of the FCB load module specifies whether the image is a 
default. (Default images may be used by the system for jobs that do not 
request a specific image.) Specify the following in the first byte: 


X'80' indicates a default image 
X'00' indicates a nondefault image 
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3. The second byte of the load module indicates the number of bytes to be 
transferred to the control unit to load the FCB image. This count includes 
the byte, if used, for the print position indexing feature. 





4. The third byte of the load module (the first byte of the FCB image) is either 
the print position indexing byte, or the lines-per-inch byte. The print 
position indexing byte is optional and, when used, precedes the 
lines-per-inch byte. The 3262 Model 5, 4245, and 4248 Printers accept and 
discard the index byte if it is present, because neither printer supports the 
indexing feature. A description of the print position indexing feature and its 
use will be found in IBM 3211 Printer, 3216 Interchangeable Train 
Cartridge, and 3811 Printer Control Unit Component Description and 
Operator’s Guide. 


The special index flag in the third byte contains X'80' plus a binary index 
value, from 1 to 32 (the default is 1). This index value sets the left margin: 
1 indicates flush-left; any other value indicates a line indented that many 
spaces. 


The form image begins with the lines-per-inch (LPI) byte. The LPI byte 
defines the number of lines per inch (6 or 8) and also represents the first line 
of the page. 
Note: Printers controlled by JES2 require a channel 1 identifier here. 
Typically, the length of an FCB image is consistent with the length of the 
form it represents. For example, an 8-1/2 inch form to be printed at 6 LPI os ok 
has an FCB image that is 51 bytes long (8-1/2 inches times 6 LPI). ; 
The LPI byte appears as follows: 
X'1n' sets 8 LPI 
X'On' sets 6 LPI 
5. All remaining bytes (lines) must contain X'On', except the last byte, which 
must be X'1n'. The letter n can be a hexadecimal value from 1 to C, 
representing a channel (one to 12), or it can be 0, which means no channel 
is indicated. 
In Figure 45 on page 221, an FCB load module is assembled and added to 


SYS1.IMAGELIB. The image defines a print density of 8 lines per inch on an 
11-inch form, with a right shift of 15 line character positions (1-1/2 inches). 


wo 
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//ADDFCB JOB MSGLEVEL=1 


//STEP EXEC PROC=ASMFCL, PARM.ASM='NODECK,LOAD', 
// PARM. LKED='LIST,OL,REFR, RENT, XREF' 
//ASM.SYSIN DD * 
FCB2ID1 CSECT 
*THIS EXAMPLE IS FOR A FORM LENGTH OF 11 INCHES WITH 8 LPI (88 LINES) 
DC X'80' THIS IS A DEFAULT IMAGE 
DC AL1 (89) LENGTH OF FCB IMAGE AND INDEXING BYTE 
DC X'8F' OFFSET 15 CHARACTERS TO THE RIGHT 
DC X'10' 8 LINES PER INCH-NO CHANNEL FOR LINE 1 
DC XL4'0' 4 LINES NO CHANNEL 
DC X'O1' CHANNEL 1 IN LINE 6 
DC XL6'0O' 6 LINES NO CHANNEL 
DC X'02' CHANNEL 2 IN LINE 13 
DC XL6'0' 6 LINES NO CHANNEL 
DC Os" CHANNEL 3 IN LINE 20 
DC XL6'O' 6 LINES NO CHANNEL 
DC X'04' CHANNEL 4 IN LINE 27 
DC XL6'0O' 6 LINES NO CHANNEL 
DC X'O5' CHANNEL 5 IN LINE 34 
DC XL6'0O' 6 LINES NO CHANNEL 
DC X'06' CHANNEL 6 IN LINE 41 
DC XL6'0O' 6 LINES NO CHANNEL 
DC X'07' CHANNEL 7 IN LINE 48 
DC XL6'O' 6 LINES NO CHANNEL 
DC x'08' CHANNEL 8 IN LINE 55 
DC XL6'0' 6 LINES NO CHANNEL 
DC x'09' CHANNEL 9 IN LINE 62 
DC XL6'0O' 6 LINES NO CHANNEL 
ae DC X'OA' CHANNEL 10 IN LINE 69 
( DC XL6'O' 6 LINES NO CHANNEL 
4 DC X'OB' CHANNEL 11 IN LINE 76 
DC XL6'0' 6 LINES NO CHANNEL 
DC X'OC' CHANNEL 12 IN LINE 83 
DC XL4'O' 4 LINES NO CHANNEL 
DC Xx'10' POSITION 88 LAST LINE IN IMAGE 
END 
/* 
//UKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(FCB2ID1) ,DISP=OLD, 
// SPACE= (OVERRIDE SECONDARY ALLOCATION) 


Figure 45. Sample Code to Assemble and Add an FCB Load Module to SYS1.IMAGELIB 





Notes to Figure 45: 
| 1. The RENT and REFR linkage editor attributes are required. 


2. Executing the ASMEFCL procedure does not actually generate executable 
code. The assembler/linkage editor is used to place the FCB image into 
SYS1.IMAGELIB. 


3. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 
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Retrieving an FCB Image from SYS1.IMAGELIB 





If you want to modify an FCB image in virtual storage before loading it into a 
forms control buffer, you can use this sequence of macro instructions to read the 
FCB image into virtual storage. 


1. An IMGLIB macro instruction, along with the OPEN parameter 


2. A BLDL macro instruction to determine whether the FCB image you want 
is in the image library 


3.. A LOAD macro instruction to load the image into virtual storage 


After the image has been read in, you should issue the IMGLIB macro 
instruction with the CLOSE parameter and the address of the DCB that was | 
built by the first IMGLIB macro. A SETPRT macro instruction can be used to 
load the forms control buffer with the modified image. Printers other than the 
3800 require the use of an FCB entry in an exit list, as described in Data 
Administration Guide. 


The format of the BLDL and SETPRT macros is given in Data Administration: 
Macro Instruction Reference; the format of the LOAD macro is given in 
Supervisor Services and Macro Instructions. 


The format of the IMGLIB macro is shown below: 


[symbol] | IMGLIB {OPEN | CLOSE, addr} 


OPEN 
specifies that a DCB is to be built for SYS1.IMAGELIB and that 
SYS1.IMAGELIB is to be opened. The address of the DCB is returned in 
register 1. 


CLOSE 
specifies that SYS1.IMAGELIB is to be closed. 


addr 
specifies the RX-type address of the word that points to the DCB. If 
coded in the form (reg), the register in parentheses then contains the 
address of the DCB, not the address of the fullword. 


Return codes from the IMGLIB OPEN macro are shown below: 


O(X'00' Operation successful. 


( ) 
4(X'04"') Either the volume containing SYS1.IMAGELIB is not 










mounted or a required catalog volume is not mounted. 
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8(X'08') Either SYS1.IMAGELIB does not exist on the volume to 


which the catalog points, or SYS1.IMAGELIB is not 
cataloged. 


12(X'0C') An error occurred in reading the catalog or VTOC. 


BLDL and LOAD are the only macros that may refer to the DCB built by the 
IMGLIB macro. 
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UCS Alias Names 





Chapter 8. JES2 Support for the IBM 1403, 3203 Model 5, and 
3211 Printers 


The system assigns an alias for each installation-standard print chain not actually 
defined on a given printer. This provides JES2 with flexibility in scheduling 
printers for SYSOUT data sets. For example, a request for the 1403 TN train 
would be assigned the T11 train if the data set were printed on a 3211. The 
assigned alias names that follow the naming conventions currently used in 
SYS1.IMAGELIJB are: 


Image 


UCS1AN 
UCS1HN 
UCS1IPN 
UCS1TN 
UCS2A11 
UCS2H11 
UCS2P11 
UCS2T11 


Alias 


UCSIA11 
UCS1H11 
UCS1P11 
UCSI1TI1 
UCS2AN 
UCS2HN 


UCS2PN,UCS2RN,UCS2QN 


UCS2TN 


The image and alias names are included in SYS1.IMAGELIB at system 


generation. 


Some trains, such as SN and G11, do not have aliases because neither has an 
equivalent train on the other printer. An installation can assign an alias, if it so 
chooses. (For details about the ALIAS statement, see Linkage Editor and 
Loader User’s Guide.) If an alias is supplied, JES2 will use it. If an alias is not 
supplied, an installation-defined SYSOUT class or a printer routing code 
(specified via the DEST parameter) should be used to assign the data set to the 
correct printer. If a SYSOUT class or a printer routing code is not used and if 
JES2 is directed to print a data set on a printer for which the proper image is not 
supplied, JES2 notifies the operator. The operator can then print the data set 
with a valid train or redirect the data set to the proper printer via the '$E' 


command. 


If an installation defines a new train, it can supply an alias name for that train, 
via the linkage editor ALIAS statement, when including the image in 
SYS1.IMAGELIB. 
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The 3211 Indexing Feature 





JES2 supports the 3211 Indexing Feature in two ways: 
1. Specification of the INDEX parameter on the /*OUTPUT card. 
2. The extended FCB image: 


JES2 supplies two special FCBs: FCB26 for 6 lines per inch and FCB28 for 
8 lines per inch (specified as FCB=6 and FCB=8, respectively). These 
FCBs contain a channel 1 indication in position 1, a special index flag in the 
third byte, and the number of lines per inch in the fourth byte of the image. 


The special index flag in the third byte of FCB26 and FCB28 contains 
X'80' plus a binary index value, in the range 1 to 32 (default=1). The 
index value sets the left margin (1 indicates flush-left position; other values 
cause indentation of the print line by N-1 positions). 


If any other FCB images are to be used by JES2, they must specify channel 
1 in position 1; otherwise, JES2 incorrectly positions the forms in the 
printer. (STD1 and STD2 do not specify channel 1 in position 1 and 
therefore must not be specified, unless altered, for JES2.) 


If the third byte of any other FCB image contains a data character 
(specifying the number of lines per inch) other than X'80', JES2 uses that 


specification and supplies an index value of 1. , 
IBM 3203 Model 5 Printer 


The IBM 3203 Model 5 Printer is treated as a 3211 Printer by JES2, except that 
the 3203 Model 5 does not support the 3211 indexing feature, and any indexing 
commands from JES2 are ignored by the 3203 Model 5. The 3203 Model 5 uses 
3211 FCB images and its own unique UCS images. UCS images are listed in 
System Generation. 
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Chapter 9. CATALOG, SCRATCH, and RENAME Dummy Modules 


The detailed information about installation-replaceable Catalog, Scratch, and 
Rename dummy modules that appeared in this chapter has been moved to Data 
Facility Product: Customization. 


You can replace these modules to invoKe special processing either before or after 


CATALOG (SVC26), SCRATCH (SVC 29), or RENAME (SVC 30) 
processing. 
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Chapter 10. Specifying Buffer Numbers for DASD Data Sets 


The BUFNO keyword in the DCB macro and the BUFNO subparameter of the 
DCB keyword in the DD statement determine how many buffers are allocated 
when accessing a partitioned or sequential data set using QSAM. The NCP 
keyword in the DCB macro determines how many un-CHECKed READ or 
WRITE macro instructions are allowed when accessing a sequential or 
partitioned data set using BSAM; one buffer is used for each READ or WRITE 
macro instruction. 


The sequential access method can construct a channel program to transfer as 
many as 30 buffers or 240000 bytes of data, whichever is less. If BUFNO or 
NCP is less than 30, no more than that number of buffers can be transferred 
with a single channel program. 


BUFNO is defaulted in OPEN to five if it is not specified fora QSAM DCB; 
NCP is defaulted to one in OPEN if it is not specified. The QSAM access 
method manages buffers. The user program must manage buffers when it uses 
BSAM. 


Performance Considerations 


Buffer number and block size influence the rate at which data can be transferred 
and the operating system overhead per block. The use of more buffers reduces 
(per block transferred) the EXCP and IOS overhead and the time waiting for the 
DASD device to seek to the requested cylinder and rotate to the requested 
record (device latency time). However, if more buffers are allocated than a 
program can effectively process, the virtual pages containing those buffers will 
be paged out, effectively adding to the system overhead for the job. A large 
number of buffers also cause a large amount of real storage to be allocated to 
the job while the data is being transferred. 


A job in a low-performance group may get swapped out more frequently than a 
higher priority job. The number of buffers allocated for the job contributes to 
the number of pages that have to be swapped out. 


Programs that access data sets with small block size (for example, 80) can easily 
make effective use of 30 buffers, which fit in, at most, two 4096-byte pages. 
The advantage of 30 buffers over the default of five buffers is great: one 
channel program versus six channel programs to transfer 30 blocks. 


At the other end of the spectrum, usage of data sets with large blocking factors 


such as full-track blocking on 3350 or half-track blocking on 3380 can still be 
effective when only three or four buffers, rather than five or more, are specified. 
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The slightly lower DASD performance and small increase in EXCP and IOS 
instruction costs should be more than offset by a reduction in paging or . 
swapping in a constrained environment. ‘ey 


It can be seen that proper selection of buffer number can have a positive effect 
on the elapsed time of a job and the system overhead associated with the job. 
The DCB OPEN installation exit can use installation criteria for a default buffer 
number for QSAM DCBs (for a description of the OPEN installation exit, see 
Data Facility Product: Customization.) The NCP field of the DCB must be set by 
the program for BSAM DCBs. 
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Appendix A. CVAF VTOC Access Macros 


CVAFDIR Macro 


Overview of the CVAFDIR Macro 


Syntax 


For an indexed or nonindexed VTOC, you may use the CVAFDIR macro to: 


Read or write a DSCB by specifying the name of the data set it represents 


Read or write a DSCB by specifying its address 


In addition, for an indexed VTOC, the macro may be used to: 


Read or write VTOC index records 


Read and retain in virtual storage the first high-level VIER, and VIERs used 
during an index search. 


Read and retain in virtual storage the space map VIRs 


Free VIRs retained in virtual storage 


[label] CVAFDIR | ACCESS=READ | WRITE | RLSE 
[,DSN=addr| 

[,BUFLIST=addr] 

[, VERIFY=YES | NO] 

[,UCB=(reg) | DEB=addr] 

[ TOAREA=KEEP | (KEEP,addr)NOKEEP | 


(NOKEEP,adadr)| 
[.MAPRCDS=YES | (YES,addr) | NO | 
(NO,adadr)| 
[,.LXRCDS=KEEP | (KEEP,addr) | NOKEEP | 
(NOKEEP, addr)| 
[,BRANCH=YES! | NO | (YES,SUP) | (YES,PGM)] 
[.MF=I | L | (E,addr )) 





1The default is SUP if YES is coded. 
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ACCESS: Read or Write a DSCB or VIR(S), or Release Buffer Lists ~, 


When ACCESS is READ or WRITE, a single DSCB is accessed for an indexed Nee” 
or nonindexed VTOC, or one or more VIRs are accessed for an indexed VTOC. 


ACCESS=READ 
Specifies that a single DSCB or one or more VIR(s) are to be read into a 
buffer whose address is in a buffer list. 


If the buffer list if for a DSCB, only one entry is used in the buffer list. 
The first entry with the skip bit set to zero and a nonzero buffer address is 
used. 


All VIR(s) whose buffer list entry has the skip bit off will be read into a 
buffer. 


DSN and BUFLIST are required if ACCESS=READ for a DSCB buffer 
list. 


ACCESS=WRITE 
Specifies that a single DSCB or one or more VIRs are to be written from 
buffer(s) whose address is in a buffer list. 


WRITE is permitted with BRANCH=NO only if the caller is authorized 
by APF. 


DSN and BUFLIST are required if ACCESS=WRITE for a DSCB buffer 
list. 


If any buffer list entry has its modified bit set, only those entries with the 
modified bit set will be written. If no modify bits are on, all VIRs will be 
written. 


ACCESS=RLSE 
Applies only to VIR buffer lists. It requests the release of one or more 
buffers in the VIR buffer list chain identified in the BUFLIST keyword, 
and the release of each buffer list for which all buffers are released. 


DSN and BUFLIST are not required if ACCESS=RLSE. 


Only buffers in the buffer list with the skip bit set to zero and with a 
nonzero buffer address are released. The buffer list is not released if any 
entry has the skip bit set to one. 


For an indexed VTOC, if ACCESS=RLSE is coded, buffer lists and 
buffers pointed to by the BUFLIST keyword will be released, along with 
buffer lists supplied in the CVAF parameter list CVMRCDS and 
CVIRCDS fields. If the CVMRCDS or the CVIRCDS buffers are 
supplied in the BUFLIST field, either directly or indirectly through 
chaining, the keyword MAPRCDS= YES, [IXRCDS=KEEP, or 
MAPRCDS=(NO,0), IXRCDS=(NOKEEP,0) must be coded to prevent 
CVAF from freeing the buffers more than once. If buffers are released, ~ 
the CVAF parameter list field pointing to the buffer list will be updated. f | 
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DSN: Specify the Name of the DSCB 


DSN=addr 
DSN specifies the address of a 44-byte data set name of the DSCB to be 
accessed. 


DSN is required if ACCESS=READ or WRITE and the request is to read 
or write a DSCB. If a 140-byte DSCB is specified: 


e CVAF validity checks the storage location, but ignores the contents of 
the location. 


e You must specify an argument that points to an extent within the 
VTOC. 


BUFLIST: Specify One or More Buffer Lists 


BUFLIST=addr 
The BUFLIST keyword contains the address of a buffer list used to read 
or write a DSCB or VIRs. 


VERIFY: Verify that a DSCB is a Format-0 DSCB 


VERIFY=YES 
CVAF will verify that the DSCB is a format-0 DSCB before writing the 
DSCB. The first four bytes of the key will be compared with binary zeros. 
If the key does not start with four bytes of zeros, the DSCB will not be 
written and an error code will be returned. 


VERIFY=NO 
CVAF will not test the key of the DSCB. 


Note: VERIFY applies only when writing a 140-byte DSCB. VERIFY is 
ignored when a VIR is written. 


UCB | DEB: Specify the VTOC to Be Accessed 


UCB=(reg) 
Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caller must not use this parameter. 


Note: Code the address of the UCB parameter as register (2-12). 
Coding an RX-Type address here gives you unpredictable results. 


If the address of a previously obtained I/O area is supplied through the 
IOAREA keyword, neither UCB nor DEB need be supplied. Otherwise, 
either a UCB or DEB must be supplied. If a UCB address is supplied, it 
will be overlaid in the CVPL by the UCB address present in the I/O area. 


DEB=addr | 
Specifies the address of a DEB opened to the VTOC you want to access. 
CVAF does not allow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
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perform any asynchronous activity (such as EXCP, CLOSE, EOV) Pa 
against the data set represented by the DEB because CVAF removes the a * 
DEB from the DEB table for the duration of the CVAF call. If you are WY 
not authorized (neither APF authorized nor in a system key) you must 

specify a DEB address, not a UCB, to CVAFDIR. See “Identifying the 

Volume” on page 42 for further details. 


If you supply both the DEB and the UCB in the CVPL, the DEB address will be 
used and the UCB address will be overlaid in the CVPL by the UCB address in 
the DEB. 


IOAREA: Keep or Free the I/O Work Area 


IOAREA=KEEP | 
Specifies the CVAF I/O area associated with the CVAF parameter list is 
to be kept upon completion of the CVAF request. IOAREA=KEEP may 
bé coded with BRANCH=NO only if the caller is authorized (APF or 
system key). 


If IOAREA=KEEBP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caller of CVAF. 


Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, as certain initialization functions can be bypassed. Neither DEB 
nor UCB need be specified when a previously obtained CVAF I/O area is 
supplied; neither can they be changed. 


When IOAREA=KEFPP is first issued, CVAF returns the CVAF I/O area 
in the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. | 


When processing on the current volume is finished, release all areas that 
were kept. 


IOAREA=(KEEP, addr) 
Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained I/O area may be 
passed to CVAF by coding its address as the second parameter of the 
IOAREA keyword. 


IOAREA=NOKEEP 
Causes the work area to be freed upon completion of the CVAF request. 


IOAREA=(NOKEEP, addr) 
Causes a previously obtained work area to be freed upon completion of 
the CVAF request. 
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MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers 


This keyword applies to an indexed VTOC only and specifies the disposition of 
the MAPRCDS buffer list and buffers. 


MAPRCDS=YES 
Specifies that the buffer list and buffers are to be retained at the end of 
processing. 


If no buffer list address is in the CVAF parameter list, CVAF will read 
the MAP VIRs into buffers it obtains. The buffer list that contains the 
address and RBAs of the VIRs can be accessed after processing from the 
CVAF parameter list field, CVMRCDS. The buffer list and VIR buffers 
are in your protect key: subpool 0 if you are not authorized; 229 if you 
are. 


When processing on the current volume is finished, release all areas that 
were kept. 


MAPRCDS=(YES, addr) 
If YES is coded and the buffer list address (CVMRCDS in CVAF 
parameter list) is supplied, VIRs are not read. 


The CVMRCDS buffer list used in CVAFDIR macro can be passed to 
another CVAF macro call through the MAPRCDS keyword. 


If MAPRCDS=YES is coded for a nonindexed VTOC, the function is 
performed, but an error code will be returned. 


MAPRCDS=NO 
If MAPRCDS=NO is coded, all the buffers without the skip bit on in the 
buffer list whose address is in the CVMRCDS field of the CVPL will be 
freed. If all the buffers are freed, the buffer list will also be freed. 


MAPRCDS=(NO,addr) 
Causes buffer lists and buffers previously obtained by CVAF to be freed. 


You must free buffer lists and buffers obtained by CVAF. This can be done in 
one of three ways: 


e By coding MAPRCDS=NO on the CVAFDIR macro that obtained the 
buffers 


e By coding MAPRCDS=NO on a subsequent CVAF macro 


e By coding CVAFDIR ACCESS=RLSE and providing the address of the 
buffer list in the BUFLIST keyword 


Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of MAP records read. 
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IXRCDS: Retain VIERS in Virtual Storage 
This keyword applies to indexed VTOCs only. 


IXRCDS=KEEP 
Specifies that VIERs read into storage are to be kept in virtual storage. 
The VIERs are retained even if processing cannot complete successfully. 
The CVAF parameter list in field CVIRCDS contains the address of a 
buffer list with the VIR buffer addresses and RBAs of the VIERs read. 


The index search function will dynamically update the buffer list and, 
when necessary, obtain additional buffer lists and chain them together. 


If KEEP is specified and no buffer list is supplied to CVAF in the CVPL, 
CVAF will obtain a buffer list and buffers and read the first high-level 
VIER. The address of the buffer list is placed in the CVMICDS field of 
the CVPL. The first high-level VIER will be checked for the VXFHLV 
bit and to see whether the VXVISE bit is off. 


The buffer list and VIR buffers are in your protect key. The subpool is 0 
if you are not authorized; it is subpool 229 if you are. 


If IXRCDS=KEEP is coded for a nonindexed VTOC, a request to read or 
write a DSCB will be performed, but an error code will be returned. 


When processing on the current volume is finished, release all areas that 
were kept. 


IXRCDS=(KEEP, addr) 
The index records buffer list address from one CVAF request is being 
passed to this CVAF parameter list by specifying its address as the second 
parameter in the IXRCDS keyword. 


IXRCDS=NOKEEP 
If NOKEEP is coded, the VIERs that are accessed (if any) are not 
retained. Furthermore, the buffer list supplied in the CVIRCDS field in 
the CVAF parameter list is released, as are all buffers found in the buffer 
list. If the skip bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 


IXRCDS=(NOKEEP, addr) 
Specifies that previously accessed VIERs are not to be retained. 


You must free buffer lists and buffers obtained by CVAF. This can be dane in 
one of three ways: 


¢« By coding IXRCDS=NOKEEP on the CVAFDIR macro that obtained the 
buffers 


e By coding IXRCDS=NOKEEP on a subsequent CVAF macro 


e By coding CVAFDIR ACCESS=RLSE and providing the address of the 
buffer list in the BUFLIST keyword 
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Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the VIERs read. 





BRANCH: Specify the Entry to the Macro 


BRANCH=(YES,SUP) 
Requests that the branch entry to CVAFDIR be used. You must be in 
supervisor state. Protect key checking is bypassed. 


An 18-word save area must be supplied if BRANCH=YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 


BRANCH=YES 
Equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is bypassed. 


BRANCH=(YES,PGM) 
Requests the branch entry. You must be authorized by APF and be in 
problem state. Protect key checking is bypassed. 


BRANCH=NO 
Requests the SVC entry. You must be authorized by APF if any output 
operations are requested. Protect key checking is performed. 


_ MEF: Specify the Form of the Macro 


( : This keyword specifies whether the list, execute, or normal form of the macro is 
requested. : 


MF=I 
If I is coded or if neither L nor E is coded, the CVAF parameter list is 
generated and CVAF is called. This is the normal form of the macro. 


MF=L 
L indicates the list form of the macro. A parameter list is generated, but 
CVAF is not called. 


MF=(E,addr) 


E indicates the execute form of the macro. The CVAF parameter list 
whose address is in X'addr' can be modified by this form of the macro. 


Appendix A. CVAF VTOC Access Macros 237 








Return Codes from the CVAFDIR Macro 


On return from CVAF, register 1 contains the address of the CVPL (CVAF 
parameter list), and register 15 contains one of the following return codes: 


Code 


00(X'00') 


04(X'04") 


08(X'08') 


12(X'0C') 


16(X'10') 
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Meaning 


The request was successful. However, if the CVAFDIR request is 
to read or write a DSCB and a VTOC index structure error is 
encountered, the CVSTAT field indicates the structure error 
encountered. (CVSTAT code descriptions are in 

Appendix C, ‘“VTOC Index Error Message and Associated 
Codes” on page 297.) 


An error occurred. The CVSTAT field in the CVPL contains an 
indication of the cause of the error. (CVSTAT code descriptions 
are in Appendix C, “WTOC Index Error Message and Associated 
Codes” on page 297.) 


Invalid VTOC index structure while processing a request to read 
or write a VTOC index record. The CVSTAT field in the CVPL 
contains an indication of the cause of the error. (CVSTAT code 
descriptions are in Appendix C, “WTOC Index Error Message 
and Associated Codes” on page 297.) 


The CVAF parameter list is not in your protect key or is invalid 
(the ID is invalid, or the length field is incorrect, or the CVFCTN 
field is invalid). The CVPL has not been modified. | 


An I/O error was encountered. 


























CVAFDSM Macro 


Overview of the CVAFDSM Macro 
The CVAFDSM macro may be used for an indexed VTOC to: 
e Obtain one or more extents that describe unallocated space on the volume 
e Obtain a count of free DSCBs on the VTOC 


e Obtain a count of free VTOC index records in the VTOC index. 


Syntax 


[label] CVAFDSM | ACCESS=MAPDATA 
MAP=INDEX | VOLUME | VTOC 
[ EXTENTS=adadr]| 
[.MAPRCDS=YES! | (YES,addr) | NO? | 
(NO,addr)| 
[,UCB=(reg) | DEB=adar] 


[| COUNT=YES | NO] 
[| ,CTAREA=addr] 
[ TOAREA=KEEP | (KEEP,addr) | NOKEEP | 
(NOKEEP,addr)| 
| [,BRANCH=NO | YES; | (YES,SUP) | (YES,PGM)] 
[|.MF=I| L | (E,addr)] 





1 Default if MF=I. 
2 Default if MF=L or MF=(E,addr). 


3 Default is SUP if YES is coded. 


ACCESS=MAPDATA: Request Information from the Index Space Maps 
ACCESS=MAPDATA 
Obtains data from the index space maps. Three kinds of data are 


available: 


e The number of format-0 DSCBs (the data is obtained from the VTOC 
map of DSCBs) 


e The number of unallocated VIRs in the index (the data is obtained 
from the VTOC index map) 


e The number (and location) of extents of unallocated pack space (the 
data is obtained from the VTOC pack space map) 


Appendix A. CVAF VTOC Access Macros 239 











MAP: Identify the Map to Be Accessed 


MAP=INDEX 


Specifies that the VTOC index map (VIXM) is to be accessed and a count 


of unallocated VIRs returned. COUNT=YES must also be coded. 


MAP=VOLUME 
Specifies that the VTOC pack space map (VPSM) is to be accessed and 
information on unallocated extents of pack space returned. 
EXTENTS=addr and COUNT=NO must also be coded. 


MAP=VTOC 
Specifies that the VTOC map of DSCBs (VMDS) is to be accessed and a 
count of format-O DSCBs returned. COUNT=YES must also be coded. 


EXTENTS: Identify Where Extents from the VPSM Are Returned 


EXTENTS=addr 
If one or more extents from the VPSM are requested, EXTENTS is the 
address of a 1-byte count field containing the number of 5-byte extents 
that follow. In the first two bytes of the first 5-byte extent, you must 
supply the relative track address (RTA) at which CVAF should start the 
VPSM search. The first extent area is updated with information on the 
next free extent found that has a higher starting RTA than that supplied. 
Each subsequent extent area is filled in with information on free space 
extents (in ascending track address order). 


Information on free extents has the format, XX YYZ, where: 

e XX is the relative track address of the first track of the extent. 
e YY is the number of whole cylinders in the extent. 

e Z is the number of additional tracks in the extent. 


Only XX is supplied by the caller in the first extent area. CVAF will start 
searching the VPSM at relative track address XX. 


If all the unallocated extents in the VPSM are provided before filling in all 
the supplied extent areas, the remaining extent areas are set to zero. 
Register 15 is set to 4 on return, with the CVSTAT field in the CVPL set 
to X'20' to indicate end of data. 


MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers 


MAPRCDS=YES 
Specifies that the buffer list and buffers are to be retained at the end of 
the function. 


If YES is specified and no buffer list is supplied through the CVAF 
parameter list, CVAF will read the MAP VIRs into buffers obtained by 
CVAF. The buffer list that contains the address and RBAs of the VIRs 
can be accessed after the CVAF call from the CVAF parameter list field, 
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CVMRCDS. The buffer list and VIR buffers are in the caller’s protect 
key: subpool 0 if the caller is not authorized; subpool 229 if the caller is 
authorized. 


YES is the default if MF=I is specified or defaulted. 


When processing on the current volume is finished, release all areas that 
were kept. 


MAPRCDS=(YES, addr) 
If YES is coded, but the buffer list address (CVMRCDS in CVAF 
parameter list) is supplied, the VIRs are not read. 


The CVMRCDS buffer list from one CVAF call can be passed to another 
CVAF macro call through the MAPRCDS keyword. 


MAPRCDS=NO 
If MAPRCDS=NDO is coded, the MAP records buffers and buffer list will 
be freed upon completion of the CVAFDSM function. 
NO is the default if MF=L is specified. 


MAPRCDS=(NO,addr) 
Causes buffer lists and buffers previously obtained by CVAF to be freed. 


Buffer lists and buffers obtained by CVAF must be freed by the caller. This can 
be done in one of three ways: 


e By coding MAPRCDS=NO on the call that obtained the buffers. 
e By coding MAPRCDS=NO on a subsequent CVAF call. 


e By calling CVAFDIR ACCESS=RLSE and providing the buffer list in the 
BUFLIST keyword. 


If MF=(E,addr) is coded and MAPRCDS is not coded, the parameter list 
value of MAPRCDS is not changed. 


Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the MAP records read. 


UCB | DEB: Specify the VTOC to Be Accessed 


UCB=(reg) 
Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caller may not supply a UCB to CVAF. 


Note: Code the address of the UCB parameter only as register (2-12). 
Coding an RX-Type address here gives you unpredictable results. 


DEB=addr 
Specifies the address of a DEB opened to the VTOC you want to access. 
CVAF does not allow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
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perform any asynchronous activity (such as EXCP, CLOSE, EOV) 
against the data set represented by the DEB because CVAF removes the 
DEB from the DEB table for the duration of the CVAF call. If you are 
not authorized (neither APF authorized nor in a system key) you must 
specify a DEB address, not a UCB, to CVAFDSM. See “Identifying the 
Volume” on page 42 for further details. 


If a previously obtained CVAF I/O area is supplied through the IOAREA 
keyword, neither UCB nor DEB need be supplied. Otherwise, either a UCB or 
DEB must be supplied. If a UCB address is supplied, it will be overlaid in the 
CVPL with the UCB address in the I/O area. 


If DEB and UCB are supplied in the CVPL, the DEB will be used, and the UCB 
address supplied will be overlaid in the CVPL with the UCB address obtained 
from the DEB. 


COUNT: Obtain a Count of Unallocated DSCBs or VIRs 


COUNT=YES 


Indicates that a count of unallocated DSCBs or VIRs in the designated 
space map is requested. MAP=VTOC or MAP=INDEX must be 
specified if COUNT= YES is coded. 


COUNT=NO 


Indicates that a count of unallocated DSCBs or VIRs is not desired but, 
rather, information on free space on the pack is desired. 
MAP=VOLUME must be coded if COUNT=NO is coded or defaulted. 


CTAREA: Supply a Field to Contain the Number of Format-0 DSCBs 


CTAREA=addr 


Gives the address of a 4-byte field to contain the number of format-0 
DSCBs when COUNT=YES, MAP=VTOC is specified; or the number of 
unallocated VIRs in the VTOC index when COUNT= YES, 
MAP=INDEX< is specified. 


IOAREA: Keep or Free the I/O Work Area 


IOAREA=KEEP 


Specifies that the CVAF I/O area associated with the CVAF parameter 
list is to be kept upon completion of the CVAF request. 
IOAREA=KEEP may be coded with BRANCH=NO only if the caller is 
authorized (APF or system key). 


If IOAREA=KEFBP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caller of CVAF. 


Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, as certain initialization functions can be bypassed. Neither DEB 
nor UCB need be specified when a previously obtained CVAF I/O area is 
supplied; neither can they be changed. 
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When IOAREA=KEFPP is first issued, CVAF returns the CVAF I/O area 
in the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. 


When processing on the current volume is finished, release all areas that 
were kept. 


IOAREA=(KEEP, addr) 
Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained CVAF I/O area 
may be passed to CVAF by coding its address as the second parameter of 
the IOAREA keyword. 


IOAREA=NOKEEP 
Causes the work area to be freed upon completion of the CVAF request. 


IOAREA=(NOKEEP, addr) 
Causes a previously obtained work area to be freed upon completion of 
the CVAF request. 


BRANCH: Specify the Entry to the Macro 


BRANCH=(YES,SUP) 
Requests that the branch entry to CVAFDIR be used. The caller must be 
in supervisor state. Protect key checking is bypassed. 


An 18-word save area must be supplied if BRANCH=YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 


BRANCH=YES 
Is equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is bypassed. 


BRANCH=(YES,PGM) 
Requests the branch entry. The caller must be APF authorized and in 
problem state. Protect key checking is bypassed. 


BRANCH=NO | 
Requests the SVC entry. The caller must be APF authorized if any output 
operations are requested. Protect key checking is performed. 


MEF: Specify the Form of the Macro 


This keyword specifies whether the list, execute, or normal form of the macro is 
requested. 


MF=I 
If I is coded or if neither L nor E is coded, the CVAF parameter list is 
generated, as is code, to call CVAF. This is the normal form of the 
macro. 
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MF=L | o~ 
L indicates the list form of the macro. A parameter list is generated, but ‘ 


code to call CVAF is not generated. 

MF=(E,addr) 
E indicates the execute form of the macro. The remote CVAF parameter 
list supplied as X'addr' is used in, and can be modified by, the execute 
form of the macro. 

Return Codes from the CVAFDSM Macro 

On return from CVAF, register 1 contains the address of the CVPL (CVAF 

parameter list), and register 15 contains one of the following return codes: 

Code Meaning 

0(X'00') The request was successful. 

4(X'04') End of data (CVSTAT is set to decimal 32), or an error was 
encountered. The CVSTAT field in the CVPL contains an indication 
of the cause of the error. (CVSTAT code descriptions are in 
Appendix C, “WTOC Index Error Message and Associated Codes” 
on page 297) 


8(X'08') = Invalid VTOC index structure. CVSTAT contains an indication of | 
the cause of the error. (CVSTAT code descriptions are in ee? 


Appendix C, ““VTOC Index Error Message and Associated Codes” 
on page 297) 


12(X'0C') The CVAF parameter list is not in your protect key or is invalid (the 
ID is invalid, or the length field is incorrect, or the CVFCTN field is 
invalid). The CVPL has not been modified. 


16(X'10') AnJI/O error was encountered. 
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CVAFFILT Macro 





Overview of the CVAFFILT Macro 


You may use the CVAFFILT macro to invoke the CVAF filter service. You 
may also use it to map or initialize the CVAF parameter list (CVPL). To 
accommodate the FSA address, the CVPL generated by CVAFFILT is 4 bytes 
longer than the CVPL generated by the other CVAF macros. CVAF filter 
retrieves data set DSCB chains from an indexed or nonindexed VITOC and 
places them in buffers you provide. You may request the DSCBs for a single 
partially qualified data set name or for a list of fully qualified data set names. 
You must identify a specific DASD device and provide both a filter criteria list 
(FCL) defining the request, and a CVAF buffer list (with buffers) for DSCB 
return. The format of the two elements of the FCL is shown in Figure 18 on 
page 54 and Figure 19 on page 56. The format of the buffer list is shown in 
“Buffer Lists” on page 45. CVAFFILT returns a complete set of DSCBs in the 
order that they are chained in the VITOC (format-1, format-2, then format-3). 





Note: Keywords coded on the list form of the macro need not be coded on the 
execute form. Keywords coded on one CVAFFILT call remain in effect for 
subsequent calls unless overridden, if you use the same CVAFFILT parameter 
list. 





Syntax 





[label] CVAFFILT | [,ACCESS={READ | RESUME | RLSE3] 
[,BUFLIST= addr | (reg)}] 
[ {UCB= {addr | (reg)} | DEB= {addr | (reg)}] 
[,FCL= {addr | (reg)}] 
[,.FLTAREA={KEEP | KEEP, {addr | (reg)} | 


NOKEEP | NOKEEP, {adar | (reg)}}] 
[ TOAREA={KEEP | KEEP, {addr | (reg)} | 
NOKEEP | NOKEEP, {adar | (reg)}}] 
| .BRANCH=${NO | YES | (YES,{SUP | PGM})}] 
[{MF=I | MF=D | MF=L | MF=(E,faddr | (reg))}] 





Note: For the first operand following CVAFFILT, you must not code the 
leading comma. 


Control Block Address Resolution: 
Keyword= addr | (reg) 


You, as the caller, either define or reference the control blocks needed by CVAF 
filter (caller-defined control blocks are: BUFLIST, CVPL, and FCL. 
Caller-referenced control blocks are: DEB, FLTAREA, IOAREA., and UCB). 
The CVAFFILT macro generates different instructions for keyword=addr and 
Bt: keyword=(reg) depending upon whether you are specifying a ‘‘defined”’ or 
( referenced" control block. | 
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When you specify any control block’s address as '(reg)', the CVAFFILT 
macro assumes that the register specified contains that address. 


When you specify a ‘‘defined” control block’s address as 'addr', the 
CVAFFILT macro assumes that the specified location is that of the control 
block itself. The macro generates a load address instruction (LA) to obtain 
the control block’s address. 


When you specify a “referenced” control block’s address as 'addr', the 
CVAFFILT macro assumes that the specified location is that of a fullword 
containing the address of the control block. The macro generates a load 
instruction (L) to obtain the control block’s address. 


ACCESS: Retrieve or Resume Retrieving a DSCB, or Release FLTAREA and/or IOAREA 
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ACCESS=READ 


Retrieves all DSCBs associated with the data set name(s) specified in the 
filter criteria list (FCL), placing them in your buffers. You can select 
(filter) the retrieved DSCBs by providing either a list of one or more fully 
qualified names, or a single partially qualified name, using single or double 
asterisk notation. (See the example of partially qualified names in 
“Examples of Partially Qualified Names for CVAFFILT” on page 250.) 


If the number of buffers is not large enough to hold all the requested 
DSCBs, CVAFFILT indicates this in the CVSTAT status byte of the 
CVAF parameter list (CVPL). You can resume the READ function by 
issuing a call with ACCESS=RESUME. See “Codes Put in the CVSTAT 
Field” on page 298. 


When selecting DSCBs by partially qualified name, CVAFFILT uses only 
the first data set name in the FCL list. You must set the FCLCOUNT 
count field in the FCL to '1' or CVAFFILT returns error code 63 in the 
CVSTAT status byte of the CVPL. The DSCBs returned by CVAFFILT 
may not be in sequence by data set name; however, the DSCBs for each 
data set are always in order (format-1, format-2, format-3). 


When selecting DSCBs by fully qualified names, you may request that 
CVAF filter return the DSCBs for the selected data set names in the data 
set name order implied by the FCL. See the FCL1ORDR flag in 

Figure 18 on page 54. 


You should always test the status byte of each data set name in the FCL 
list to ensure successful completion (Some error conditions result in failure 
to return a data set’s DSCBs). See the FCLDSNST byte in Figure 19 on 
page 56. 


ACCESS=RESUME 


Resumes a previously initiated READ or RESUME function that was 
terminated because you did not provide enough buffers to contain all the 
requested DSCBs. For the RESUME function to execute correctly, you 
must have coded the keyword FLTAREA=KEEP in each of the previous 
READ and RESUME function calls. 
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ACCESS=RLSE 





Releases the previously kept filter save area (FLTAREA) and/or CVAF 
I/O work area (IOAREA). 


UCB | DEB: Specify the VTOC to Be Accessed 


UCB=addar | (reg) 


Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. If you are not authorized, you cannot supply a UCB to CVAF. 
CVAF returns CVSTAT '8' and return code '4' if you specify a UCB 
and you are not authorized. 


DEB=addr | (reg) 


Specifies the address of a DEB opened to the VTOC you want to access. 
If you are not authorized, you cannot perform any asynchronous activity 
against the data set represented by the DEB (such as EXCP, CLOSE, 
EOV), because CVAF removes the DEB from the DEB table for the 
duration of the CVAF call. If you are not authorized (neither APF 
authorized nor in a system key) you must specify a DEB address, not a 
UCB, to CVAFFILT. See “Identifying the Volume” on page 42 for 
further details. 


BUFLIST: Specify a Buffer List 


BUFLIST=addar | (reg) 





The BUFLIST keyword specifies the address of a buffer list used to read 
DSCBs. When you specify ACCESS=RLSE, the BUFLIST keyword is 
required for the standard form of the macro. See the format of the buffer 
list header and buffer list entry in Figure 15 on page 46 and Figure 16 
on page 47, respectively. 


FCL: Specify a Filter Criteria List 


FCL=adadr | (reg) 


The FCL keyword specifies the address of a filter criteria list. It is 
required when ACCESS=READ is specified on the standard form of the 
macro. The format of the two elements of the filter criteria list is shown 
in Figure 18 on page 54 and Figure 19 on page 56. 


FLTAREA: Keep or Free the Filter Save Area 


FLTAREA=KEEP 


Specifies keeping the filter save area. You must code this operand if the 
RESUME function might be called later (to resume processing 
prematurely terminated because the number of caller-supplied buffers is 
not enough to contain all the returned DSCBs). 


CVAFFILT returns the address of the kept filter save area in the 
CVAFFILT parameter list (CVFSA field). If you specify the same 
parameter list in subsequent RESUME calls, CVAFFILT reuses the same 
filter save area. 
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Note: If you code this operand, you must subsequently issue CVAFFILT nat 
with ACCESS=RLSE to release the filter save area. | 


FLTAREA=(KEEP, {addr | (reg)}) 
Specifies the address of a previously obtained filter save area. See the 
description of FLTAREA=KEEP operand for additional concerns. 


FLTAREA=NOKEEP 
Frees the filter save area upon completion of the CVAF request. 


FLTAREA=(NOKEEP, {addr | (reg)}) 
Frees a previously obtained filter save area upon completion of the CVAF 
request. 


IOAREA: Keep or Free the I/O Work Area 


IOAREA=KEEP 
Specifies keeping the CVAF I/O work area. For authorized callers, 
CVAFFILT returns the address of the kept I/O work area in the 
CVAFFILT parameter list (CVIOAR). If you specify the same parameter 
list in subsequent calls, CVAFFILT reuses the same I/O work area. 


Note: If you code this operand, you must subsequently issue CVAFFILT 
with ACCESS=RLSE to release the I/O work area. 


IOAREA=(KEEP, addr | (reg)}) = 
Provides the address of a previously obtained filter save area. See the 
description of LOAREA=KEEP operand for additional concerns. Se 


IOAREA=NOKEEP 
Frees the filter save area upon completion of the CVAF request. 


IOAREA=(NOKEEP, {adar | (reg)}) 
Frees a previously obtained CVAF I/O work area upon completion of the 
CVAF request. 


BRANCH: Specify the Entry to the Macro 


BRANCH=NO 
Requests the SVC (default) entry. Protect key checking is performed. 


BRANCH=YES 
Equivalent to BRANCH=(YES,SUP), because SUP is the default when 
you code YES. You must be in supervisor state. Protect key checking is 
bypassed. 


BRANCH=(YES,SUP) 
Requests the branch entry. You must be in supervisor state. Protect key 
checking is bypassed. You must supply an 18-word save area if you 
specify BRANCH=YES. You cannot hold a lock at entry to CVAF. You 
cannot be in SRB mode. 
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BRANCH=(YES,PGM) 
Requests the branch entry. You must be APF authorized and be in 
problem state. Protect key checking is bypassed. 











MEF: Specify the Form of the Macro 


Specifies whether the DSECT, list, execute, or normal form of the macro is 
requested. You can be in either 24-bit or 31-bit addressing mode. If you are not 
authorized, you must pass the address of a DEB built by OPEN. If you are 
authorized, you may pass either the DEB address or the UCB address. You 
must ensure that the volume is allocated and will remain mounted (for example, 


by dynamic allocation). 


MF=I 


Specifies the standard form of the macro. The CVAF parameter list is 
generated and CVAF is called. 'MF=I' is the default value. 


MF=D 





Specifies the DSECT form of the macro. The macro generates a request 
for the ICVAFPL macro to map the unique CVAF filter CVPL (4-bytes 
longer than standard CVPL). 


MF=L 


Specifies the list form of the macro. The CVAF parameter list is 
generated, but CVAF is not called. 


MF=(E, {addr | (reg)}) 
Specifies the execute form of the macro. The CVAF parameter list whose 
address is in 'addr' or 'reg' is used. You can modify the parameter list 
with this form of the macro. 


Return Codes from the CVAFFILT macro 


CVAF filter service does not issue any messages. Upon completion of a filter 
request, register 15 contains one of the following return codes: 


Code 

00(X'00') 
04(X'04') 
08(X'08') 
12(X'0C') 


16(X'10') 


Meaning 

The request was successful. 

Logical error; status information in CVSTAT. 
Invalid VTOC structure. 

CVAFFILT parameter list in wrong key, or invalid. 


I/O error. 


Note: CVSTAT in the CVAF parameter list explains the status codes. See 
“Codes Put in the CVSTAT Field” on page 298 for a list of the status codes. 
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Examples of Partially Qualified Names for CVAFFILT 


CVAFFILT supports partially qualified data set names using single or double ee 
asterisk notation as shown below: 


e You may use a single asterisk to represent a single qualifier. For example, 
SYS1.*.LOAD designates any data set with three qualifiers, the first being 
SYS1, the second being any qualifier, and the third being LOAD. 


e You may also use a single asterisk to represent zero or more unspecified 
characters. For example, LOAD.*LIB designates any data set having only 
two qualifiers, with LOAD being the first, and the second qualifier ending 
with the character string LIB (for example, LINKLIB). The asterisk may 
appear anywhere within the qualifier. You may use two single asterisks in 
the following way: LOAD.A*B*.LIB. CVAFFILT does not support the use 
of two or more single asterisks with any other character within a single 
qualifier (for example, LOAD.B**.LIB is invalid). 


e A double asterisk represents a place holder for zero or more qualifiers. For 
example, SYS1.** designates any data set having SYS1 as its first or only 
qualifier. 
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CVAFSEQ Macro 


Overview of the CVAFSEQ Macro 
The CVAFSEQ macro may be used to: 
e Read an indexed VTOC sequentially in data-set-name (DSN) order 


e Read an indexed VTOC or a nonindexed VTOC in physical-sequential order 





Syntax 





[label] CVAFSEQ | ACCESS=GT | GTEQ 
[| .BUFLIST=adadr] 
{,.DSN=addr] 
|,UCB=(reg) | DEB=addr]| 
|,.DSNONLY=NO | YES] 
|,ARG=addr] 


[ IOAREA=KEEP | (KEEP,addr) | NOKEEP | 
(NOKEEP,addr)| 

[,.IXRCDS=KEEP | (KEEPaddr) | NOKEEP | 
(NOKEEP, addr)] 

[,BRANCH=NO | YES' | (YES,SUP) | (YES,PGM)] 

[.MF=I | L | (E,addr)) 





1 If YES, default is SUP. 


ACCESS: Specify Relationship between Supplied and Returned DSN 


ACCESS=GT 
Specifies that the DSN or argument value is to be used to return a DSCB 
whose DSN or argument is greater than that supplied. 


ACCESS=GTEQ 
Specifies that the DSN or argument value is to be used to return a DSCB 
whose DSN or argument is greater than or equal to that supplied. 


Note: A CVAF call specifying ACCESS=GTEQ should be followed by 
an ACCESS=GT request, or the same DSCB or name will be returned. 


BUFLIST: Specify One or More Buffer Lists 
BUFLIST=addr 


The BUFLIST keyword supplies the address of a buffer list used to read 
or write DSCBs and VIRs. 
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DSN: Specify Access by DSN Order or by Physical-Sequential Order ae 


DSN=addr oa 
Specifies that access of an indexed VTOC is by DSN order. BUFLIST is 
required if DSNONLY=NO is coded or defaulted. 


DSN omitted 
If you omit the DSN keyword, access of an indexed or nonindexed VTOC 
is by physical-sequential order. BUFLIST is required. 


Note: If the order is physical-sequential, you must initialize the argument field 
in the first buffer list entry to zero or to the argument of the DSCB. If the 
argument is zero (BFLEARG=00), the read begins at the start of the VTOC. 
You must be authorized (APF or system key) to read multiple DSCBs with a 
single invocation of the CVAFSEQ macro. See “Initiating Physical-Sequential 
Access”’ on page 51 for more information. 


UCB | DEB: Specify the VTOC to Be Accessed 


UCB=(reg) 
Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caller may not supply a UCB to CVAF. 


Note: Code the address of the UCB parameter only as register (2-12). 
Coding an RX-type address here gives you unpredictable results. 


DEB=addr : 
Specifies the address of a DEB opened to the VTOC you want to access. ae 
CVAF does not allow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
perform any asynchronous activity (such as EXCP, CLOSE, EOV), 
against the data set represented by the DEB because CVAF removes the 
DEB from the DEB table for the duration of the CVAF call. If you are 
not authorized (neither APF authorized nor in a system key), you must 
specify a DEB address, not a UCB, to CVAFSEQ. See “Identifying the 
Volume” on page 42 for further details. 


If a previously obtained CVAF I/O area is supplied through the IOAREA 
keyword, neither UCB nor DEB need be supplied. 


Otherwise, either a UCB or DEB must be supplied. If a UCB address is 
supplied, it will be overlaid in the CVPL with the UCB address in the I/O area. 


If you specify both DEB and UCB in the CVPL, the DEB will be used, and the 
UCB address supplied will be overlaid in the CVPL with the UCB address 
obtained from the DEB. 
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DSNONLY: Specify That Only the Data Set Name Be Read 
This keyword is applicable only to accessing an indexed VTOC in DSN order. 


DSNONLY=NO 
Requests that the data set name be obtained from the VTOC index and 
the DSCB be read into a buffer supplied through the BUFLIST keyword. 
BUFLIST is required. 


DSNONLY= YES 
Requests that only the data set name be obtained from the VTOC index. 
If the ARG Keyword is coded, the argument of the DSCB is returned. 


ARG: Specify Where the Argument of the DSCB Is to Be Returned 


This keyword is applicable only to accessing an indexed VTOC in DSN order 
with DSNONLY= YES coded. 


ARG=addr 
Provides the address of the 5-byte area where the CCHHR of each data 
set name in the VTOC index is returned when DSNONLY=YES is coded. 


IOAREA: Keep or Free the I/O Work Area 


IOAREA=KEEP 
Specifies that the CVAF I/O area associated with the CVAF parameter 
list is to be kept upon completion of the CVAF request. 
IOAREA=KEEP may be coded with BRANCH=NO only if the caller is 
authorized (APF, or system key). 


If IOAREA=KEFBP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caller of CVAF. | 


Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, because certain initialization functions can be bypassed. Neither 
DEB nor UCB need be specified when a previously obtained CVAF I/O 
area is supplied; neither can they be changed. 


When IOAREA=KEF?P is first issued, CVAF returns the CVAF I/O area. 
in the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. 


When processing on the current volume is finished, release all areas that 
were kept. 


IOAREA=(KEEP, addr) 
Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained CVAF I/O area 
may be passed to CVAF by coding its address as the second parameter of 
the IOAREA keyword. 
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IOAREA=NOKEEP 
Causes the work area to be freed upon completion of the CVAF request. ie 


genre” 


IOAREA=(NOKEEP, add) | 
Causes a previously obtained work area to be freed upon completion of . 
the CVAF request. : 


IXRCDS: Retain VIERs in Virtual Storage 
This keyword applies to an indexed VTOC only. 


IXRCDS=KEEP 
Specifies that the VIERs read into storage during the CVAF function are 
to be kept in virtual storage. The VIERs are retained even if the index 
function is unsuccessful. The VIERs are accessed from the CVAF 
parameter list (CVIRCDS). CVIRCDS is the address of a buffer list 
containing the VIR buffer addresses and RBAs of the VIERs read. 


Index search function will dynamically update the buffer list and, when 
necessary, obtain additional buffer lists and chain them together. 


If KEEP is specified and no buffer list is supplied to CVAF in the CVPL, 
CVAF will obtain a buffer list and buffers and read the first high-level 
VIER. The address of the buffer list is placed in the CVIRCDS field of 
the CVPL. The first high-level VIER will be checked for the VXFHLV 
bit and to see if the VXVISE bit is off. 


The buffer list and VIR buffers are in the caller’s protect key. The “hye 
subpool is 0 if the caller is not authorized; subpool 229 if the caller is 
authorized. 


If IXRCDS=KEEP for an nonindexed VTOC, a request to read a DSCB 
may be performed, but an error code will be returned. 


When processing on the current volume is finished, release all areas that 
were kept. 


IXRCDS=(KEEP, addr) 
The CVIRCDS from one CVAF call can be passed to another CVAF 


parameter list by specifying the address as the second parameter in the 
IXRCDS keyword. 


IXRCDS=NOKEEP 
If NOKEEP is coded, the VIERs that are accessed (if any) arenot 
retained. Furthermore, the buffer list supplied in the CVIRCDS field in 
the CVAF parameter list is released, as are all buffers found in the buffer 
list. If the skip bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 


IXRCDS=(NOKEEP, addr) 
Specifies that previously accessed VIERs are not to be retained. 





You must free buffer lists and buffers obtained by CVAF. This can be done in 
one of three ways: 
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e By coding IXRCDS=NOKEEP on the CVAFSEQ macro that obtained the 
buffers 


e By coding IXRCDS=NOKEEP on a subsequent CVAF macro 


e By coding CVAFDIR ACCESS=RLSE and providing the address of the | 
buffer list in the BUFLIST keyword 


Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the VIERs read. 


BRANCH: Specify the Entry to the Macro 


BRANCH=(YES,SUP) 
Requests that the branch entry to CVAFDIR be used. The caller must be 
in supervisor state. Protect key checking is bypassed. 


An 18-word save area must be supplied if BRANCH=YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 


BRANCH=YES 
Is equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is bypassed. 


BRANCH=(YES,PGM) 
Requests the branch entry. The caller must be APF authorized and in 
problem state. Protect key checking is bypassed. 


BRANCH=NO 
Requests the SVC entry. The caller must be APF authorized if any output 
operations are requested. Protect key checking is performed. 


MF: Specify the Form of the Macro 


This keyword specifies whether the list, execute, or normal form of the macro is 
requested. 


MF=I 
If I is coded, or neither L nor E is coded, the CVAF parameter list is 
generated, as is code, to call CVAF. This is the normal form of the 
macro. 


MF=L 
L indicates the list form of the macro. A parameter list is generated, but 
code to call CVAF is not generated. 


MF=(E,addr) 
E indicates the execute form of the macro. The remote CVAF parameter 
list supplied as 'addr' is used in and can be modified by the execute form 
of the macro. | , 
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Return Codes from the CVAFSEQ Macro 


On return from CVAF, register 1 contains the address of the CVPL (CVAF 
parameter list), and register 15 contains one of the following return codes: 


Code 


00(X'00') 


04(X'04') 


08(X'08') 


12(X'0C') 


16(X'10') 


Meaning 
The request was successful. 


End of data (CVSTAT is set to decimal 32), or an error was 
encountered. The CVSTAT field in the CVPL contains an indication 
of the cause of the error. Error descriptions are in 

Appendix C, “WTOC Index Error Message and Associated Codes” 
on page 297. 


Invalid VTOC index structure. CVSTAT contains an indication of the 
cause of the error. Error descriptions are in Appendix C, “WTOC 
Index Error Message and Associated Codes” on page 297. 


The CVPL (CVAF parameter list) is not in your protect key, or is 
invalid (the ID is invalid, or the length field is incorrect, or the 
CVFCTN field is invalid). The CVPL has not been modified. 


An I/O error was encountered. 
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( CVAFTST Macro 


Overview of the CVAFTST Macro 
The CVAFTST macro determines whether the system supports an indexed 
VTOC, and, if it does, whether the VTOC on the unit whose UCB is supplied is 
indexed or nonindexed. 
You will get a return code of 12 if CVAFTST cannot determine whether an 
indexed or nonindexed VTOC is on the unit’s volume. You should not receive a 
return code of 12 from CVAFTST if you have opened a data set (including the 
VTOC) on the volume. 


You need no authorization to issue the CVAFTST macro. 


Syntax 


[label] CVAFTST | UCB=(reg) 


UCB: Specify the VTOC to Be Tested 


UCB=(reg) 
Supplies the address of the UCB for the volume whose VTOC is to be 
tested. 





Note: Code the address of the UCB parameter only as register (2-12). 
Coding an RX-type address here gives you unpredictable results. 
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Return Codes from the CVAFTST Macro 


On return from CVAF, register 15 contains one of the following return codes: 


Code Meaning 


0(X'00') The system does not support an indexed VTOC. The volume should be 
considered to have a nonindexed VTOC. The UCB was not inspected 
to determine its validity or status. 


4(X'04') The system supports an indexed VTOC, but the volume has a 
nonindexed VTOC. 


8(X'08') The system supports an indexed VTOC and the volume has an indexed 
VTOC. 


12(X'0C') The system supports an indexed VTOC, but the volume is not mounted 
or the VIB is not initialized for it; thus, the status (indexed or 
nonindexed) of the VTOC cannot be determined. 


16(X'10') The system supports an indexed VTOC, but the unit is not a DASD or 
has a VIO UCB, or the UCB address is invalid. 
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Appendix B. Examples of VTOC Access Macros 


The examples that follow are partial assembler listings that include expansions of 
each VTOC access macro. The expansions are provided to show how the 
VTOC macros can be substituted for existing procedures. 


Example 1: Using the CVAFDIR Macro with an Indexed or 
Nonindexed VTOC 


This example uses the CVAFDIR macro to read a DSCB of a given data set 
name and determines whether the DSCB is for a partitioned data set. The 
address of the 44-byte data set name is supplied to the program in register 5 
(labeled RDSN in the example). The address of a DEB open to the VTOC is 
supplied to the program in register 4 (labeled RDEB in the example). 


The buffer list is in the program and is generated by the ICVAFBFL macro. The 








DSCB buffer is in the program and is generated by the IECSDSL1 macro. 


EXAMPLE1 CSECT 
STM 14,12,12(RSAVE) 
BALR 12,0 
USING *,12 
ST RSAVE, SAVEAREA+4 
LA RWORK , SAVEAREA 
ST RWORK , 8 (, RSAVE) 
LR RSAVE , RWORK 
(ES ESS SES ESE SEE EE SES ESS SESS SESE SESS SSS SSS SSS SESS SESE SSS SSS SSS SS 
* 


REGISTERS 
* 

Pee EEE EE EEE SE EE EES EEE REESE EEE ES ESE EES ESE SEE ESE SESE SESE SES EE ES 
REG1 EQU 1 REGISTER 1 

RWORK EQU 3 WORK REGISTER 

RDEB EQU 4 DEB ADDRESS 

RDSN EQU 5 ADDRESS OF DATA SET NAME 
RSAVE EQU 13 SAVE AREA ADDRESS 

REG15 EQU 15 RETURN CODE REGISTER 15 
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= oie oie oie fe ofc fe ote oie oie oie oie fe fe ie oie ie fe ie eke ake oie ie oie fe abe fe fe 2 oe 2 oie ake oie ie 2 2 2k ake ek fe oe oie 2k ie ie oe oie oe oie 2 2k 2 2K oie oie oe ok 


t++eeteeteteeterteteeeeteret+ett 


* a 
| 
: RETURN CODES ee 
FOCI GG OGG IG GIGI IORI IG IG AOR 
PDSRTN EQU O DATA SET A PDS RETURN CODE 
NOTFND EQU 4 DATA SET NOT FOUND RETURN CODE 
NOTPDS EQU 8 DATA SET NOT A PDS RETURN CODE 
UNEXPECD EQU 12 UNEXPECTED ERROR RETURN CODE 


PEPE ELE SESE ESE SE EEE SEES ESSE SEES ES SELES ES SET SST TESTS ET TE SF 
* 

* READ DSCB INTO DS1FMTID. 

* DATA SET NAME ADDRESS SUPPLIED IN RDSN. 

* ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

* DETERMINE IF DATA SET IS A PARTITIONED DATA SET. 

* THIS PROGRAM IS NEITHER REENTRANT NOR REUSABLE. 

# 
* 


2 He Re Hee Ae HE He AE Ee HE HE ER HE RE A HE HE ie EO 
XC BUFLIST (BFLHLN+BFLELN) , BUFLIST ZERO BUFFER LIST 


OL BFLHFL, BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHNOE, 1 ONE BUFFER LIST ENTRY 
LA RWORK ,DS1FMTID ADDRESS OF DSCB BUFFER 
ST RWORK, BFLEBUF PLACE IN BUFFER LIST 
OL BFLEFL, BFLECHR CCHHR OF DSCB RETURNED BY CVAF 
MVI BFLELTH,DSCBLTH DATA PORTION OF DSCB READ - DSN * 
SUPPLIED IN CVPL 

MVC DS1DSNAM,0(RDSN) MOVE IN DATA SET NAME TO WORKAREA 
CVAFDIR ACCESS=READ , DSN=DS 1DSNAM, BUFLIST=BUFLIST, DEB= (RDEB) 
CNOP 0,4 
BAL 1,ICV1E LOAD CVPL LIST ADDRESS 

ICV1S EQU * START OF CVPL 
DC CL4'CVPL' EBCDIC 'CVPL' 
DC AL2 (ICV1E-ICV1S) LENGTH OF CVPL 
DC XL1'01' FUNCTION CODE Mos 
DC XL1'0OO!' STATUS INFORMATION 
DC B'OQOOOO00N0' FIRST FLAG BYTE 
DC B'OOOOO0000' SECOND FLAG BYTE 
DC H'O' RESERVED 
DC A(Q) UCB ADDRESS 
DC A(DS1DSNAM) DATA SET NAME ADDRESS 
DC A(BUFLIST) BUFFER LIST ADDRESS 
DC A(0) INDEX VIR'S BUFFER LIST ADDRESS 
DC A(0) MAP VIR'S BUFFER LIST ADDRESS 
DC A(0) I/O AREA ADDRESS 
DC A(0) DEB ADDRESS 
DC A(O) ARGUMENT ADDRESS 
DC A(0) SPACE PARAMETER LIST ADDRESS 
DC A(0) EXTENT TABLE ADDRESS 
DC A(0) NEW VRF VIXM BUFFER LIST ADDR 
DC A(Q) VRF DATA ADDRESS 
DC A(0) COUNT AREA ADDRESS 

ICV1E EQU * END OF CVPL 
ST RDEB, 36(,1) STORE DEB PTR IN PARM LIST 
SVC 139 
USING CVPL,REG1 ADDRESSABILITY TO CVPL 
LTR REG15,REG15 ANY ERROR 
BZ NOERROR BRANCH IF NOT 
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oe oe Re ee ee ke ee 2 2 ke 2 ie eR RK KK EE KE 
* 
* DETERMINE WHAT ERROR IS 
* 
OR A A A A A A I A A A RR OR IR RK ROKK 
Cc REG15,ERROR4 IS RETURN CODE 4 
BNE OTHERERR BRANCH IF NOT 4 
CLI CVSTAT,STATOO1 IS IT DATA SET NAME NOT FOUND? 
BNE OTHERERR BRANCH IF NOT 


DROP REG1 ADDRESSABILITY TO CVPL NOT NEEDED 
Of ee 2 ee 2 ke 2 ie ie ie 2 eke eke 2 eee ke 2 de ke ee ie ee ee ie oa ee ie a oo a 


ok 
a DATA SET NAME NOT FOUND 
* 
9K 9K 3 i ak 3K 2K 2 2 ok a oe Kk oe oe ok 2k OK ok oie 2 oe a ok i 3 OK oe ok i Kk 2K Oe oe ok Kk OK oe 2 ok oe a 2 ok ke ke ok ok 2 ok ok ok Ke eK Kk ok ke 
L RSAVE,4(,RSAVE) 
RETURN (14,12) ,RC=NOTFND SET UP DATA SET NOT FOUND ERROR 





+ LM 14,12,12(13) RESTORE THE REGISTERS 
+ LA 15,NOTFND (0,0) LOAD RETURN CODE 
+ BR 14 RETURN 
NOERROR EQU- * DSCB READ 
MVC F1CCHHR, BFLEARG MOVE CCHHR OF FORMAT 1/4 DSCB TO * 
WORKAREA 


CLI DS1FMTID,C'4' 
BE NOTF 1 


IS DSCB A FORMAT 4 DSCB 
BRANCH IF YES. NOT A FORMAT 1 


TM DS 1DSORG , DS 1DSGPO IS FORMAT 1 DSCB FOR PARTITIONED * 
DATA SET 
BO PDS BRANCH IF PDS 
NOTF 1 EQU * DSCB IS NOT A PDS 


L RSAVE,4(,RSAVE) 





RETURN (14,12) ,RC=NOTPDS 


+ LM 14,12,12(13) 

+ LA 15,NOTPDS (0,0) 

+ BR 14 

PDS EQU * 

L RSAVE,4(,RSAVE) 
RETURN (14,12) ,RC=PDSRTN 

+ LM 14,12,12(13) 

+ LA 15,PDSRTN (0,0) 

+ BR 14 


OTHERERR EQU * 
L RSAVE,4(,RSAVE) 


SET UP NOT PDS RETURN CODE 
RESTORE THE REGISTERS 
LOAD RETURN CODE 
RETURN 

DATA SET IS PARTITIONED 


SET UP PDS RETURN CODE 
RESTORE THE REGISTERS 
LOAD RETURN CODE 
RETURN 

UNEXPECTED ERROR 


RETURN (14,12) ,RC=UNEXPECD 


+ LM 14,12,12(13) 
+ LA 15,UNEXPECD (0,0) 
+ BR 14 


ERROR4 DC F'4' 
BUFLIST ICVAFBFL DSECT=NO 


RESTORE THE REGISTERS 
LOAD RETURN CODE 
RETURN 


ERROR RETURN CODE 4 
BUFFER LIST 


fRHEKKKKKKKKKKKKKKKKKKKKAKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KK KK KK 


WSS SESS LESSEE EEE EE SLE LEE SESE EEE SEE SESE SEES EEE ESE EEE ESTEE EES EE ETE EE REE SS SS SE 


+%* BUFFER LIST HEADER 
+BUFLIST DS OF 


+BFLHNOE DS XL1 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
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+BFLHFL 

+ 
+BFLHKEY 
+BFLHVIR 
+BFLHDSCB 
+ 
+BFLHSP 
+BFLHFCHN 
+% 
+BFLHLN 


+% 


+BFLE 
+BFLEFL 
+BFLERBA 
+BFLECHR 
+BFLETTR 
+BFLEAUPD 
+BFLEMOD 
+BFLESKIP 
+BFLEIOER 
+ 
+BFLELTH 
+% 
+BFLEARG 
+ 
+BFLEATTR 
+ 
+BFLEARBA 
+BFLEBUF 
+BFLELN 


+IECSDSL1 
+IECSDSF1 
+DS1DSNAM 
+DS1FMTID 
+DS1DSSN 
+DS1VOLSQ 
+DS1CREDT 
+DS1EXPDT 
+DS 1NOEPV 
+DS 1NOBDB 
4% 

+ 
+DS1SYSCD 
+ 
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DS 
ORG 
DS 

EQU 


EQU. 


DS 
DS 
DS 


EQU 


DS 
DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 

DS 


DS 
ORG 
DS 
ORG 
DS 
DS 
EQU 





XL1 
BFLHFL 
XL1 
X'08' 
X'O4' 
XL 1 
XL 1 

A 


*-BUFLIST 


OF 
XL1 
X'80' 
X'40' 
X'20' 
X'10' 
X'0O8' 
X'O4' 
X'02' 
XL 1 
XL1 


XL5 
BFLEARG+ 1 
XL3 
BFLEARG+1 
XL4 

A 

*—-BFLE 


ITECSDSL1 (1) 


EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 


DS 
DS 
DS 


* 


IECSDSL1 
CL44 

CL1 

CL6 

XL2 

XL3 

XL3 

XL 1 

XL1 


XL 1 
CL13 
XL7 





KEY AND FLAG BYTE 


PROTECT KEY (FIRST 4 BITS) 
BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 


RESERVED 


SUBPOOL OF BUF. LIST/BUFFERS 


FORWARD CHAIN PTR TO NEXT BUF. 


LIST 


LENGTH OF BUFFER LIST HEADER 
pA he He ie Ae 2 eRe AE 2K AE A A AE A AE A HE ER AE AE HE A A A EH A I 


BUFFER LIST ENTRY : 
TEEPE ELE LE LEE EE ESSE EE EES ESET SEES TESST SESE ES ESSE TESTS TST TEST TT TTT Te ee SS 


BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 
ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 


DATA IN BUF. HAS BEEN MODIFIED 


SKIP THIS ENTRY 


I/O ERROR 
RESERVED 


LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB (CCHHR) 


'TTR' OF ARGUMENT 


"RBA' OF ARGUMENT 
BUFFER ADDRESS 


LENGTH OF A BUFFER LIST ENTRY 


FORMAT 1 DSCB DATA SET NAME AND 
BUFFER 
FORMAT 1 DSCB 


DATA SET NAME 
FORMAT IDENTIFIER 
DATA SET SERIAL NUMBER 
VOLUME SEQUENCE NUMBER 
CREATION DATE 
EXPIRATION DATE 
NUMBER OF EXTENTS ON VOLUME 
NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 





* 





££ 
bid 


eo a 





+DS1DSORG DS XL2 DATA SET ORGANIZATION 








+% FIRST BYTE OF DS1DSORG 

+DSIDSGIS EQU X'80' IS - INDEXED SEQUENTIAL JO1A 
+% ORGANIZATION 

+DS1DSGPS EQU  xX'40' PS - PHYSICAL SEQUENTIAL JO1A 
++ ORGANIZATION 

+DS1DSGDA EQU  X!'20' DA - DIRECT ORGANIZATION dO1A 
+DS1DSGCX EQU  X!'10' CX - BTAM OR QTAM LINE GROUP dO1A 
+* EQU  xX'O8' RESERVED QO1A 
+* EQU  xX'04' RESERVED dO1A 
+DS1DSGPO EQU xX'02' PO - PARTITIONED ORGANIZATION 401A 
+DS1DSGU EQU x'O01' U - UNMOVABLE, THE DATA JO1A 
++ CONTAINS LOCATION DEPENDENT 

+ INFORMATION 

+* 

+% SECOND BYTE OF DS1DSORG 

+DS1DSGGS EQU  xX'80' GS - GRAPHICS ORGANIZATION DO1A 
+DS1DSGTX EQU  xX'40' TX - TCAM LINE GROUP a01A 
+DS1DSGTQ EQU  xX!'20' TQ - TCAM MESSAGE QUEUE JO1A 
+% EQU  xX!'10' RESERVED A01A 
+DS1ACBM EQU  X'08' ACCESS METHOD CONTROL BLOCK QO1A 
+DS1DSGTR EQU X'04' TR - TCAM 3705 QO1A 
+* EQU  X'02' RESERVED JO1A 
+* EQU xX'O1' RESERVED DO1A 
+DS1RECFM DS XL1 RECORD FORMAT 

+DS10OPTCD DS 4 OPTION CODE 

+DS1BLKL DS XL2 BLOCK LENGTH 

+DS1LRECL DS XL2 RECORD LENGTH 

+DS1KEYL DS XL1 KEY LENGTH 

+DS1RKP DS xi? RELATIVE KEY POSITION 

+DS1DSIND DS XL1 DATA SET INDICATORS 

+DS1SCALO DS XL4 SECONDARY ALLOCATION 

+DS1LSTAR DS XL3 LAST USED TRACK AND BLOCK ON TRACK 
+DS1TRBAL DS XL2 BYTES REMAINING ON LAST TRACK USED 

+ DS XL2 RESERVED 

+DS1EXT1 DS XL10 FIRST EXTENT DESCRIPTION 

+* FIRST BYTE EXTENT TYPE INDICATOR 

+% SECOND BYTE EXTENT SEQUENCE NUMBER 

+# THIRD - SIXTH BYTES LOWER LIMIT 

+% SEVENTH - TENTH BYTES UPPER LIMIT 

+DS1EXT2 DS XL10 SECOND EXTENT DESCRIPTION 

+DS1EXT3 DS XL10 THIRD EXTENT DESCRIPTION 

+DS1PTRDS DS XL5 POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 


+DS1END EQU- * 
DSCBLTH EQU ¥*-IECSDSL1-L'DS1DSNAM LENGTH OF DATA PORTION OF DSCB 


F1CCHHR DS XL5 CCHHR OF DSCB 
SAVEAREA DS 18F SAVE AREA 
CVPL ICVAFPL , CVPL MAPPING MACRO 


twee ee eee ee ee Ee EE EE EEE EE EE EEE EES ES EEE EES EEE SES EE SES ESSE SES SEE ES SE SS 


+* CVAF PARAMETER LIST 
TEER ELE LE LESS ELE SE EES SEES SESE ESTES EE SSE SPSS EC SSCS SSCS Te TST CTS STS TTS TS SS 


+CVPL DSECT CVAF PARAMETER LIST 
+ DS OF 

+CVLBL DS CL4 EBCDIC: *CVPL’ 
+CVLTH DS H LENGTH OF CVPL 
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+CVFCTN 
+CVDIRD 
+CVDIWR 
+CVDIRLS 
+CVSEQGT 
+CVSEQGTE 
+CVDMIXA 
+CVDMIXD 
+CVDMALC 
+CVDMRLS 
+CVDMMAP 
+CVVOL 
+CVVRFRD 
+CVVRFWR 
+CVSTAT 

+ 

+CVFL1 
+CV1IIVT 
+CV1IOAR 
+CV1PGM 
+CV1MRCDS 
+CV1IRCDS 
+CV 1MAPIX 
+CV1MAPVT 
+CV 1MAPVL 
+CVFL2 
+CV2HIVIE 
+CV2VRF 
+CV2CNT 
+CV2RCVR 
+CV2SRCH 
+CV2DSNLY 
+CV2VER 
+CV2NLEVL 
+% 

+ 

+CVUCB 
+CVDSN 
+CVBUFL 
+CVIRCDS 
+CVMRCDS 
+CVIOAR 
+CVDEB 
+CVARG 
+CVSPACE 
+CVEXTS 
+CVBUFL2 
+CVVRFDA 
+CVCTAR 
+CVPLNGTH 


+ 





DS 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


~ EQU 


EQU 
EQU 
EQU 
DS 


DS 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
EQU 


PrPPrrrrrrrrrrra 


*-CVPL 


VALUES OF CVSTAT 





FUNCTION BYTE 


CVAFDIR ACCESS=READ f~ 
CVAFDIR ACCESS=WRITE or 
CVAFDIR ACCESS=RLSE No 


CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST * 
BELOW) | 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

TOAREA=KEEP 

BRANCH= (YES, PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES ; 
VERIFY=YES ee 
OUTPUT-NEW HIGHEST LEVEL VIER \ 
CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
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END 

















Example 2: Using the CVAFDIR Macro with an Indexed VTOC 


This example uses the CVAFDIR macro to read one or more DSCBs on a 
VTOC. The UCB is supplied to the program in register 4 (labeled RUCB). The 
TTR of each DSCB read is to be returned to the caller. This program must be 
APF authorized. 


The address of a parameter list is supplied to the program in register 5 (labeled 
RLIST). The parameter list contains one or more 3-word entries. The format of 
each 3-word entry is mapped by the LISTMAP DSECT. The first word contains 
the address of the data set name of the DSCB to be read. The second word 
contains the address of the 96-byte buffer into which the DSCB is to be read. 
The third word contains the address of the 3-byte TTR of the DSCB read. 


The CVPL is generated by a list form of the CVAFDIR macro at label CVPL. 
The BUFLIST, IXRCDS, IOAREA, and BRANCH keywords are coded on the 
list form of the macro. IXRCDS=KEEP and IOAREA=KEEP are coded to 
avoid overhead if two or more DSCBs are to be read. BRANCH=(YES,PGM) 
is coded in the list form of the CVAFDIR macro to cause the CVPL to have the 
CV1PGM bit set to one; this will indicate to CVAF that the caller is authorized 
by APF and not in supervisor state. The execute forms of the CVAFDIR macro 
then specify BRANCH= YES, and not BRANCH=(YES,PGM), because the 
CV1PGM bit is set in the list form of the macro. 


The CVAFDIR macro with ACCESS=RLSE is coded before the program exits 
in order to release the CVAF I/O area and the index records buffer list. 
BUFLIST=0 is coded because no user-supplied buffer list is to be released; 
BUFLIST was coded on the list form of the CVAFDIR macro and, therefore, is 
in the CVBUFL field of the CVPL. This field must be set to zero for the 
release. 


EXAMPLE2 CSECT 
STM 14,12,12(13) 


BALR 12,0 
USING *,12 
Sl 13, SAVEAREA+4 


LA RWORK, SAVEAREA 
ST RWORK,8(,13) 
LR 13,RWORK 
KK Hh MK HK ke HK OK HK MK Me ok oe He ee ke ok eK KK KK KK KK Ke OK KK OK OK KK KK OK KK Ke Ke Ke Ke KK KK OK KK Ke Ke HK KK 
ae 
* REGISTERS 
* 
OK He 3 oie ok te ok oie ke oie Ke ae ok Ke ok OK ok ke 2 KK ok ok ek i ok i KK ie ok ie eK KK OK KK OK KK Ke Ke OK Ke oe ok oe Ko ok ok ok ok Ok Ok & 


RWORK EQU 3 WORK REGISTER 

RUCB EQU 4 UCB ADDRESS SUPPLIED BY CALLER 
RLIST EQU 5 ADDRESS OF PARAMETER LIST 

RDSN EQU 6 ADDRESS OF DATA SET NAME 

RTTR EQU 7 ADDRESS OF TTR 

REG15 EQU 15 RETURN CODE REGISTER 15 
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KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK ES 


* 
* READ DSCB OF DATA SET NAME SUPPLIED. RETURN TTR OF DSCB. 

* UCB ADDRESS SUPPLIED IN RUCB. 

* ADDRESS OF PARAMETER LIST IN RLIST. 

* WORD 1 OF PARAMETER LIST ADDRESS OF DATA SET NAME 

* WORD 2 OF PARAMETER LIST ADDRESS OF DSCB TO BE RETURNED 
* 
* 
* 
* 
* 


WORD 3 OF PARAMETER LIST ADDRESS OF TTR TO BE RETURNED 
WORDS 1-3 DUPLICATED WITH THE HIGH ORDER BIT OF 
WORD 3 SET TO ONE FOR LAST ENTRY. 


EEE EEE EEE EEE EE EE SE EE EEE SESS EE SESE SSE SEES EEE ES EEE SE EEE EE SS EF 


USING LISTMAP,RLIST ADDRESSABILITY TO PARMLIST 
TOPLOOP EQU #* LOOP FOR EACH DSCB 
XC BUFLIST(BFLHLN+BFLELN) ,BUFLIST ZERO BUFFER LIST 
OI BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHNOE, 1 ONE BUFFER LIST ENTRY 
LA  RWORK,LISTDSCB ADDRESS OF DSCB BUFFER 
ST  RWORK,BFLEBUF PLACE IN BUFFER LIST 
OI BFLEFL, BFLETTR TTR OF DSCB RETURNED BY CVAF 
MVI BFLELTH, DSCBLTH DATA PORTION OF DSCB READ - DSN * 
SUPPLIED IN CVPL 
L RDSN, LISTDSN ADDRESS OF DATA SET NAME 
CVAFDIR DSN=(RDSN) , UCB=(RUCB) ,MF=(E,CVPL) , BRANCH=YES 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ ST RUCB, 12(,1) STORE UCB PTR IN PARM LIST 
+ ST RDSN, 16(,1) STORE DSN PTR IN PARM LIST 
+ L 15,16 LOAD THE CVT | 
+ if — 15,328(,15) LOAD VS1/VS2 COMMON EXTENSION2 
+ i? 15, 12> 15) LOAD THE CVT CVAF TABLE 
+ L 15,0(,15) LOAD THE CVAF ADDRESS 
+ BALR 14,15 BRANCH AND LINK TO CVAF 
L RTTR,_LISTTTR ADDRESS OF TTR TO BE RETURNED 
USING TTRMAP,RTTR MAP OF TTR 
LTR REG15,REG15 ANY ERROR 
BZ NOERROR BRANCH IF NOT 
XC TPR, TTR ZERO TTR INDICATING NO DSCB 
B RELOOP GET NEXT ENTRY 
NOERROR EQU * DSCB READ 
MVC TTR,BFLEARG RETURN TTR OF DSCB 
RELOOP EQU * GET NEXT ENTRY 
TY LASTLIST,LASTBIT IS IT LAST ENTRY IN LIST? 
LA RLIST,NEXTLIST GET NEXT ENTRY 
BZ TOPLOOP PROCESS NEXT LIST 
CVAFDIR ACCESS=RLSE, RELEASE CVAF OBTAINED AREAS a 
TOAREA=NOKEEP, RELEASE IOAREA * 
IXRCDS=NOKEEP, RELEASE VIER BUFFER LIST * 
BUFLIST=0, NO USER BUFFER LIST SUPPLIED TO RLSE* 
BRANCH=YES, BRANCH ENTER CVAF * 
MF=(E,CVPL) 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ MVI 6(1),X'03! SET FUNCTION CODE 
+ NI 8(1),8° 10110114" RESET CVAF FLAGS OFF 
+ LA 15,0 GET BUFLIST ADDRESS AND 
+ ST 15,20(,1) STORE BUFLIST PTR IN PARM LIST 
+ ie 15,16 LOAD THE CVT 
+ if 15,328(,15) LOAD VS1/VS2 COMMON EXTENSION2 
+ L 15,12(,15) LOAD THE CVT CVAF TABLE 
+ L 15,0(,15) LOAD THE CVAF ADDRESS 
+ BALR 14,15 BRANCH AND LINK TO CVAF 
Le 13,SAVEAREA+4 


RETURN (14,12) 
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+ LM 14,12,12(13) RESTORE THE REGISTERS 
+ BR 14 RETURN 
BUFLIST ICVAFBFL DSECT=NO BUFFER LIST 


oe i eo i ee eK eK KK KK KK KK KK KKK KK KKK KKK HK KK KK KK KK KKK KKK KK KK KKK KK KKK KK KK 


+* BUFFER LIST HEADER 
TESST LE SE SELES EEE SESE TEES ESE SES TSS ST TTT ESET ESET STS SET TTT TTT TEST TTT ETT TS oS 


+BUFLIST DS OF BUFFER LIST HEADER 


+BFLHNOE DS XL1 NUMBER OF ENTRIES 
+BFLHFL DS XL1 KEY AND FLAG BYTE 
+ ORG BFLHFL 


+BFLHKEY DS XL1 PROTECT KEY (FIRST 4 BITS) 


+BFLHVIR EQU X'08' BUF. LIST ENTRIES DESCRIBE VIRS 
+BFLHDSCB EQU X'O4! BUF. LIST ENTRIES DESCRIBE DSCBS 
+ DS XL1 RESERVED 

+BFLHSP DS XL1 SUBPOOL OF BUF. LIST/BUFFERS 
+BFLHFCHN DS A FORWARD CHAIN PTR TO NEXT BUF. 
+* LIST 

+BFLHLN EQU *-BUFLIST LENGTH OF BUFFER LIST HEADER 


af HH He Ke he ake He He He He He He He He he He He Oe He EE ie ee Ke ke Oe Oe OK ok Oe Oe Oe OK OK KK OK KK OK OK OK OK KK KK KK KK KK KK KK KK KKK KK HK 


+* BUFFER LIST ENTRY 
TEE EE LE SLE LES ELSE EES ESE SESE SES SES ESTES TEST TEST SETS ST TTT ET ETE T ET TTT TET SF SF 


+BFLE DS OF 
+BFLEFL DS XL1 


BUFFER LIST ENTRY 
BUFFER LIST ENTRY FLAG 








+BFLERBA EQU  xX'80' ARGUMENT IS RBA 
+BFLECHR EQU  xX'4O0' ARGUMENT IS CCHHR 
+BFLETTR EQU  xX'20' ARGUMENT IS TTR 
+BFLEAUPD EQU  X'10' CVAF UPDATED ARGUMENT FIELD 
+BFLEMOD EQU- X'08' DATA IN BUF. HAS BEEN MODIFIED 
+BFLESKIP EQU xX'04' SKIP THIS ENTRY 
+BFLEIOER EQU  X'02' I/O ERROR 
+ DS XL1 RESERVED 
+BFLELTH DS XL1 LENGTH OF DSCB BUFFER OR 
+* LENGTH OF VIR DIVIDED BY 256 
+BFLEARG DS XL5 ARGUMENT OF VIR OR DSCB (CCHHR) 
+ ORG BFLEARG+1 
+BFLEATTR DS XL3 'TTR' OF ARGUMENT 
+ ORG  BFLEARG+1 
+BFLEARBA DS XL4 'RBA' OF ARGUMENT 
+BFLEBUF DS A BUFFER ADDRESS 
+BFLELN EQU  *-BFLE LENGTH OF A BUFFER LIST ENTRY 
SAVEAREA DS 18F REGISTER SAVE AREA 
LISTMAP DSECT 
LISTDSN DS  F ADDRESS OF DATA SET NAME 
LISTDSCB DS F ADDRESS OF BUFFER FOR DSCB TO BE * 
RETURNED 
LISTTTR DS OF ADDRESS OF TTR OF DSCB TO BE 
RETURNED 
LASTLIST DS X FIRST BYTE 
LASTBIT EQU  xX'80! LAST ENTRY IN LIST 
DS XL3 REMAINDER OF TTR ADDRESS 
NEXTLIST EQU * NEXT LIST 
DSCB DSECT 
IECSDSL1 (1) 
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+IECSDSL1 
+IECSDSF1 
+DS 1DSNAM 
+DS1FMTID 
+DS 1DSSN 
+DS 1VOLSQ 
+DS1CREDT 
+DS1EXPDT 
+DS 1NOEPV 
+DS 1NOBDB 
+% 

+ 
+DS1SYSCD 
+ 

+DS 1DSORG 
+% 
+DS1DSGIS 
+% 
+DS1DSGPS 
+% 
+DS1DSGDA 


- +DS 1DSGCX 


+% 

+ 

+DS 1DSGPO 

+DS 1DSGU 

+% 

+% 

+% 

+% 

+DS1DSGGS 
+DS 1DSGTX 
+DS 1DSGTQ 

+% 

+DS 1ACBM 

+DS1DSGTR 
+%* 

+% 

+DS 1RECFM 

+DS 10PTCD 
+DS 1BLKL 
+DS1LRECL 

+DS 1KEYL 
+DS1RKP 
+DS 1DSIND 
+DS 1SCALO 
+DS1LSTAR 
+DS 1TRBAL 
+ 

+DS1EXT1 
+% 

+% 

+% 

+% 

+DS 1EXT2 
+DS1EXT3 
+DS1PTRDS 
+DS 1END 
DSCBLTH 
TTRMAP 
TTR 


EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 


DS 
DS 
DS 
DS 


EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
FIRST 


SECOND BYTE 


* 





FORMAT 1 DSCB 


ITECSDSL1 

CL44 DATA SET NAME 

CL1 FORMAT IDENTIFIER 

CL6 DATA SET SERIAL NUMBER 

XL2 VOLUME SEQUENCE NUMBER 

XL3 CREATION DATE 

XL3 EXPIRATION DATE 

XL 1 NUMBER OF EXTENTS ON VOLUME 

XL1 NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 

XL 1 RESERVED 

CL13 SYSTEM CODE 

XL7 RESERVED 

XL2 DATA SET ORGANIZATION 

FIRST BYTE OF DS1DSORG 

X'80' IS - INDEXED SEQUENTIAL AaOQTA 
ORGANIZATION | 

X'40' PS - PHYSICAL SEQUENTIAL aOTA 
ORGANIZATION 

X'20' DA - DIRECT ORGANIZATION a01A 

x'10' CX —- BTAM OR QTAM LINE GROUP aO1A 

X'08' RESERVED aO1A 

X'O4' RESERVED aO1A 

X'02' PO - PARTITIONED ORGANIZATION aO1A 

X'O1' U - UNMOVABLE, THE DATA aO1A 
CONTAINS LOCATION DEPENDENT 
INFORMATION 

SECOND BYTE OF DS1DSORG 

Xx'80' GS - GRAPHICS ORGANIZATION aO1A 

X'40' TX - TCAM LINE GROUP aOTA 

X'20' TQ - TCAM MESSAGE QUEUE aO1A 

X'10' RESERVED aO1A 

X'08' ACCESS METHOD CONTROL BLOCK aO1A 

X'O4' TR - TCAM 3705 aO1A 

X'02' RESERVED aO1A 

X'O1' RESERVED aO1A 

XL 1 RECORD FORMAT 

XL1 OPTION CODE 

XL2 BLOCK LENGTH 

XL2 RECORD LENGTH 

XL 1 KEY LENGTH 

XL2 RELATIVE KEY POSITION 

XL 1 DATA SET INDICATORS 

XL4 SECONDARY ALLOCATION 

XL3 LAST USED TRACK AND BLOCK ON TRACK 

XL2 BYTES REMAINING ON LAST TRACK USED 

XL2 RESERVED 

XL10 FIRST EXTENT DESCRIPTION 

BYTE EXTENT TYPE INDICATOR 


THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 


DS 
DS 

DS 
EQU 
EQU 
DSECT 
DS 


XL10 
XL10 


XL5 
** 


*-DSCB-L'DS1DSNAM 


XL3 
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EXTENT SEQUENCE NUMBER 
LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 


POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 


LENGTH OF DATA PORTION OF DSCB 


TTR TO BE RETURNED 














EXAMPLE2 CSECT 





CVPL CVAFDIR ACCESS=READ, BUFLIST=BUFLIST,MF=L, * 
TOAREA=KEEP, KEEP IOAREA TO AVOID OVERHEAD * 
IXRCDS=KEEP KEEP VIERS FOR 2ND AND SUBSEQUENT CALLS* 
CALLED IN PROGRAM STATE BUT APF * 
AUTHORIZED SO UCB IS SUPPLIED 
+ CNOP 0O,4 
+CVPL EQU * 
+ DC CL4'CVPL' EBCDIC 'CVPL' 
+ DC AL2 (ICV8E-CVPL) LENGTH OF CVPL 
+ DC XL1'O1! FUNCTION CODE 
+ DC XL1'0OO' STATUS INFORMATION 
+ DC B'01001000! FIRST FLAG BYTE 
+ DC B'OOOOOOOO0' SECOND FLAG BYTE 
+ DC H'O' RESERVED 
+ DC A(Q) UCB ADDRESS 
+ DC A(0O) DATA SET NAME ADDRESS 
+ DC A(BUFLIST) BUFFER LIST ADDRESS 
+ DC A(0O) INDEX VIR'S BUFFER LIST ADDRESS 
+ DC A(0O) MAP VIR'S BUFFER LIST ADDRESS 
+ DC A(0) I/O AREA ADDRESS 
+ DC A(0O) DEB ADDRESS 
+ DC A(0O) ARGUMENT ADDRESS 
+ DC A(0) SPACE PARAMETER LIST ADDRESS 
+ DC A(0O) EXTENT TABLE ADDRESS 
+ DC A(0O) NEW VRF VIXM BUFFER LIST ADDR 
+ DC A(0) VRF DATA ADDRESS 
+ DC A(0O) COUNT AREA ADDRESS 
+ICV8E EQU * END OF CVPL 
ORG CVPL OVERLAY CVPL WITH EXPANSION OF MAP 
CVPLMAP ICVAFPL DSECT=NO 
( . Ke KE OK OK OK ie OK oe Ke Ko OK OK KO OK OK OK KK KK KK OK KKK KKK KKK KKK KK KKK KK KKK KK KKKK KK KKK KKK KKK KKK KK 
. +* CVAF PARAMETER LIST 
pK Ke oe 2 ok 2 Ko oe Ke oo Kk ke oe Ke ke 2 ok OK ok OK KK KK Ke Ke KK OK KOK Ke OK KK KK KK KK KK KK KK OK KK OK KK OK KK OK KK KK KK KK 
+CVPLMAP DS OF CVAF PARAMETER LIST 
+CVLBL DS CL4 EBCDIC 'CVPL' 
+CVLTH DS H LENGTH OF CVPL 
+CVFCTN DS XL 1 FUNCTION BYTE 
+CVDIRD EQU X'O1' CVAFDIR ACCESS=READ 
+CVDIWR EQU X'02' CVAFDIR ACCESS=WRITE 
+CVDIRLS EQU Xx'03' CVAFDIR ACCESS=RLSE 
+CVSEQGT EQU X'0O4' CVAFSEQ ACCESS=GT 
+CVSEQGTE EQU x'O5' CVAFSEQ ACCESS=GTEQ 
+CVDMIXA EQU X'0O6' CVAFDSM ACCESS=IXADD 
+CVDMIXD EQU X'O7' CVAFDSM ACCESS=IXDLT 
+CVDMALC EQU X'O8'! CVAFDSM ACCESS=ALLOC 
+CVDMRLS EQU x'09' CVAFDSM ACCESS=RLSE 
+CVDMMAP EQU X'OA' CVAFDSM ACCESS=MAPDATA 
+CVVOL EQU X'OB' CVAFVOL ACCESS=VIBBLD 
+CVVRFRD EQU X'OC' CVAFVRF ACCESS=READ 
+CVVRFWR EQU X'OD' CVAFVRF ACCESS=WRITE 
+CVSTAT DS XL 1 STATUS INFORMATION (SEE LIST * 
+ BELOW) 
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+CVFL1 DS X11 

+CV1IVT EQU- x'80! 
+CV1IOAR EQU  x'4O' 
+CV1PGM EQU- x'20! 
+CV1IMRCDS EQU = X'10' 
+CV1IRCDS EQU x'08' 
+CV1IMAPIX EQU x'04' 
+CV1IMAPVT EQU x'02' 
+CV1IMAPVL EQU x'0O1' 
+CVFL2 DS xU1 

+CV2HIVIE EQU x'80! 
+CV2VRF EQU- x'4O! 
+CV2CNT EQU- x'20! 
+CV2RCVR EQU- x'10! 
+CV2SRCH EQU- x'O08'! 
+CV2DSNLY EQU x'04' 
+CV2VER EQU- x'02' 
+CV2NLEVL EQU x'01' 


+% 

+ DS H 

+CVUCB DS A 

+CVDSN DS A 
+CVBUFL DS A 
+CVIRCDS DS A 
+CVMRCDS DS A 
+CVIOAR DS A 

+CVDEB DS A 

+CVARG DS A 
+CVSPACE DS A 

+CVEXTS DS A 
+CVBUFL2 DS A 
+CVVRFDA DS A 
+CVCTAR DS A 
+CVPLNGTH EQU *—-CVPLMAP 
+* VALUES OF CVSTAT 





FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 
ITOAREA=KEEP 

BRANCH= (YES , PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 
CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 


END 
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Example 3: Using the CVAFFILT Macro 


This example uses the CVAFFILT macro to read all format-1, format-2, and 
format-3 DSCBS from a given VTOC, calculates the total number of DSCBs by 


format type, and returns the totals to the calling program (the caller of this 


example program, not the caller of CVAF). The address of a DEB opened to 


the VTOC is passed to the example program in register 1 (labeled R1 in the 
example). 


The buffer list and filter criteria list are defined in the program. The 


ICVAFBFL macro generates the buffer list, and the ICVFCL macro generates 


the filter criteria list. 


EXAMPLE3 CSECT 
* 


* INPUT ... REGISTER 1 - ADDRESS OF A DEB OPENED TO THE VTOC. 

* REGISTER 13 - ADDRESS OF A STANDARD REGISTER SAVE AREA 

* REGISTER 14 - ADDRESS OF THE RETURN POINT WITHIN CALLER 
* 

* PROCESS . USE THE CVAFFILT MACRO (ACCESS=READ, ACCESS=RESUME, AND 
ACCESS=RLSE) TO READ ALL FORMAT 1, 2, AND 3 DSCBS FROM A 
* GIVEN VTOC. IF FILTER SERVICE DETECTS AN ERROR CONDITION, 
* IT RETURNS DIAGNOSTIC INFORMATION FOR DEBUGGING ANALYSIS. 
* 

* OUTPUT .. REGISTER 1 = ADDRESS OF THE DATA RETURN AREA (SEE LABEL 
+ RET$AREA AT THE END OF THIS LISTING). 

* REGISTER 15 = ZERO IF NO ERRORS WERE ENCOUNTERED. 

* OTHERWISE, ERROR INFORMATION IS PROVIDED 

* IN THE DATA RETURN AREA (SEE LABEL RET$ERR) . 
* 

* THE CVAF PARAMETER LIST (CVPL), FILTER CRITERIA LIST (FCL), BUFFER 
* LIST, AND DSCB BUFFERS ARE DEFINED WITHIN THIS CSECT. 

* 


(PEE E SESE EE EEE EERE ESE EES EEE ESE EEE SESE ESSE SEES EEE ESE SEE ESE ER SEES EE ES SE 


= EQUATES FOR ASSEMBLY CONSTANTS AND REGISTERS 
PERLE EEL EEE EEE EEE EEE EEE EEE EEE SEES EEE SESE SSE TESTE SELES ETE ESTES ESET TTT EEE 


BFLE$N EQU 11 NUMBER OF BUFFER LIST ELEMENTS AND BUFFERS DESIRED 


RO EQU 0 
R1 EQU 1 
R2 EQU 2 
R3 EQU 3 
R4 EQU 4 
R5 EQU 5 
R11 EQU 11 
R12 EQU 12 
R13 EQU 13 
R14 EQU 14 
R15 EQU 15 
* 
OK ke Ke te Ke Ke ok 2 ok Ok Ke oe Kk KK KK KK KK KK OK KK KK Ke Ke KK KK KK KK OK KK OK KKK KK KK KK KK KK KK KKK KK KK KK KK 
# SAVE CALLER'S REGISTERS AND ESTABLISH A NEW REGISTER SAVE AREA 
KK 3 OK ok ke Ke Kk OK KK OK Ke Kk Ke KK OK KK KK OK KK Ke KK ke KK KK KK KK KK KK KK HK KK KK KK KK KK KK KK KK KK KK KK KK 
STM R14,R12,12(R13) SAVE CALLER'S REGISTERS 
BALR R12,0 ESTABLISH THIS PROGRAM'S 
USING *,R12 BASE REGISTER 
ST R13,SAVEAREA+4 SAVE ADDRESS OF CALLER'S SAVE AREA 
LA R15,SAVEAREA GET ADDRESS OF THE NEW SAVE AREA 
ST R15,8(,R13) - CHAIN CALLER'S AREA TO OURS 
LR R13,R15 ESTABLISH THE NEW SAVE AREA 


PEE EEE EE SESE EE EEE EEE SESE EEE EEE ESE EE SESE SESE REESE ESE SEE EE EEE SESE EES SES 
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* ESTABLISH ADDRESSABILITY TO THE CVPL. PLACE GIVEN DEB ADDRESS 


* IN THE CVPL, INITIALIZE THE FLAG BYTE AND THE RETURN DATA AREA. 
2K ee Ke ee Re ee ER a RR RK 


LA R11,CVPL$DEF ESTABLISH ADDRESSABILITY 

USING CVPL$MAP,R11 TO THE CVPL 

ST R1,CVDEB PLACE GIVEN ADDR(DEB) IN CVPL 
MVI FLAGS , F$RSET RESET THE LOCAL FLAG BYTE 

XC RET$AREA, RET$AREA INIT. DATA RETURN AREA TO ZERO 


* 
PER EEE EEE EEE EE EEE ESE EE ESE ESE SE ESSE ESSE SEE ESS SESE ESE SEE SEES EE SEES SSS SF 


* INITIALIZE THE BUFFER LIST HEADER (BFLH) AND ELEMENTS (BFLE) 
2K 9 fe Ae 2 ee ee 2 A ee 2 9 a a oo a a a ORK RK 


XC BFLH$DEF (BFL$SIZE) ,BFLH$DEF SET BUFR LIST AREA TO ZERO 


LA R1,BFLH$DEF R1 -> BUFFER LIST HEADER 

USING BFL$MAP,R1 ESTABLISH ADDRESSABILITY 

MVI BFLHNOE, BFLE$N SET NUMBER OF BUFFER ELEMENTS 

Ol BFLHFL, BFLHDSCB IDENTIFY AS DSCB BUFR ELEMNT LIST 

LA R2,BFLH$DEF+BFLHLN R2 -> FIRST BUFFER LIST ELEMENT 

USING BFLE,R2 ESTABLISH ADDRESSABILITY 

LA R3,DSCBS$DEF R3 -> FIRST DSCB BUFFER 

LA R4,BFLE$N R4 = NUMBER OF ELEMENTS AND BUFRS 
BFLE$INT OI BFLEFL, BFLECHR REQUEST CCHHR ON RETURN 

MVI BFLELTH,DSCB$SI1Z SET BUFR LNGTH TO FULL DSCB SIZE 

ST R3,BFLEBUF SET ADDR(DSCB BUFFER) 

LA R2,BFLELN(R2) R2 -> NEXT BUFFER LIST ELEMENT 

LA R3,DSCB$SI1Z(R3) R3 -> NEXT DSCB BUFFER 

BCT R4,BFLE$INT LOOP THROUGH ALL ELEMENTS 

DROP R1,R2 | DROP TEMP USING 


* 
ee PEE EEE SEE EEE EE ES EEE EEE ESSE SE EES ESE SSE SEES ESSE TESS E ESE SE EEE EEE ESE SS 


* INITIALIZE THE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT 
PPE SEES LESSEE ES EEE SEES SEES ETS TESST TET SST TST SSCS TST TTT ST TTS ETE T ST TS 


xC FCL$DEF (FCL$SIZE) ,FCL$DEF SET FCL AREA TO ZERO 
LA R1,FCL$DEF R1 -> FCL HEADER 

USING FCL$MAP,R1 ESTABLISH ADDRESSABILITY 
MVC FCLID,FCL$ID SET THE EYECATCHER 'FCL ' 
MVC FCLCOUNT,=H'1' SET NUMBER OF FCL ELEMENTS 
LA R2,FCLHDEND R2 -> FIRST (ONLY) FCL ELEMENT 
USING FCLDSN,R2 ESTABLISH ADDRESSABILITY 
MVI FCLDSNLG,X'02' SET LENGTH(DSN PATTERN) 

LA R3,=C'**' Ro > eee 

oT R3,FCLDSNA SET ADDR(DSN PATTERN) 

DROP R1,R2 DROP TEMP USING 


* 
2A He Ae Re ee EK OK OK Kk 
* ISSUE CVAFFILT ACCESS=READ REQUEST 
OR A Ke AE Ee AE AE KE ER ER HO KK RK OR RO 
MVI RET$FTN, RETS$READ IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=READ, FCL=FCL$DEF,BUFLIST=BFLH$DEF, 
MF=(E,CVPL$DEF) 


+ LA 1,CVPL$DEF LOAD PARAMETER REG 1 

+ MVI 6(1),X'OE' SET FUNCTION CODE 

+ LA 15,FCLE$DEF GET FCL ADDRESS AND 

+ ST TS 4 T64G)) STORE FCL PTR IN PARM LIST 

+ LA 15,BFLH$DEF GET BUFLIST ADDRESS AND 

+ ST 15,20(,1) STORE BUFLIST PTR IN PARM LIST 
+ SVC 139 


* 
PEE SEES EEE EEE SESE SSE EE SESE SEE SESE SESE EES EEE ESE EEE EE SESE SESE SES SEE SES SE 


* TEST THE RETURN FROM CVAFFILT ACCESS=READ OR ACCESS=RESUME 
EEC EEL SLE LSS ES SESS ESE LETS ESE SETS E SS SCT ST TTT TS ET STS ETS TESST Te eT TS 


TEST$RET LTR R15,R15 IF DSCB RETURN IS COMPLETE 
BZ COUNTLST GO COUNT LAST SET OF DSCBS 
CH R15,=H'4' IF RETURN CODE OTHER THAN FOUR 
BNE ERR$RET GO RETURN THE ERROR CONDITION 
CLI CVSTAT, STATO64 IF OTHER THAN RESUME RECOMMENDED 
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BNE ERR$RET GO RETURN THE ERROR CONDITION 


B COUNTCUR ELSE GO COUNT CURRENT DSCB SET 
* 


PEE EE REE ELLE EEE EEE EE EEE EEE SEE EEE SEES EEE EEE SESE EES EE EEE ER EEE EES EEE FS FE 


* COUNT THE NUMBER OF FORMAT 1, 2, AND 3 DSCBS RETURNED 
PES EE LE SELES EET SET ES EE ELSE SELES ESSE ESTEE TESTS SEES ESTEE ESTES EET SE TT ES 





COUNTLST OI FLAGS , F$LAST INDICATE LAST SET OF DSCBS 
COUNTCUR LM R1,R3,RET$F1 GET PRIOR DSCB COUNTS 
LA R4,FCL$DEF R4 -> FCL HEADER 
USING FCL$MAP,R4 ESTABLISH ADDRESSABILITY 
SLR R5,R5 R5 = ZERO FOR FOLLOWING ICM 
ICM R5,B'0011',FCLDSCBR R5 = NUMBER OF DSCBS RETURNED 
BZ TST$RSUM IF ZERO, GO TEST FOR RESUME 
LA R4,DSCB$DEF R4 -> FIRST DSCB BUFFER 
USING DSCB$MAP,R4 ESTABLISH ADDRESSABILITY 
COUNTNXT CLI DS1FMTID,X'F1' IF FORMAT 1 DSCB 
BE COUNT$F1 GO INCREMENT ITS COUNTER 
CLI DS1FMTID,X'F2' IF FORMAT 2 DSCB 
BE COUNT$F2 GO INCREMENT ITS COUNTER 
LA R3,1(R3) ELSE INCREMENT FORMAT 3 DSCB COUNT 
B COUNTTST GO TEST FOR MORE DSCBS 
* 
COUNT$F2 LA R2,1(R2) INCREMENT COUNT OF FORMAT 2 DSCBS 
B COUNTTST GO TEST FOR MORE DSCBS 
x 
COUNT$F1 LA R1,1(R1) INCREMENT COUNT OF FORMAT 1 DSCBS 
COUNTTST LA R4,DSCB$SIZ(R4) R4 -> NEXT DSCB BUFFER 
BCT R5,COUNTNXT LOOP THROUGH ALL RETURNED DSCBS 
STM R1,R3,RET$F1 SAVE UPDATED DSCB COUNTS 
DROP R4 FINISHED COUNTING CURR DSCB SET 
* 
iat PEE EEE LES EEE EES EE EEE EEE ESE SESE EE SEE EEE ESE ESSE EEE EES ESE SEE EEE ES EE SE OES FE 
{ * CONDITIONALLY ISSUE CVAFFILT ACCESS=RESUME REQUEST 
(EEE EEE EE EEE EEE EE EEE EEE EEE EEE ESE SELES EE SESE EE EE EERE SEE EE EEE ES SS SE EE SS 
TST$RSUM TM FLAGS , F$LAST IF LAST SET OF DSCBS COUNTED 
BO RLSE$REQ GO REQUEST A RELEASE 
MVI RET$FTN, RET$RSUM IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=RESUME,MF=(E,CVPL$DEF) RESUME REQUEST 
LA 1,CVPL$DEF LOAD PARAMETER REG 1 
+ MVI 6(1),X'OF' SET FUNCTION CODE 
+ SVC 139 
B TEST$RET GO TEST THE RETURN CODES 


* 
(IEEE EEE EEE EEE EEE EERE SEE EEE EE EEE EEE EE EEE EEE ESE SESE EES EEE EER EEE EE EE EE SE 


* ISSUE CVAFFILT ACCESS=RLSE REQUEST 
EEE ELLE EEE E SEES EES ESE SETS TESTS TESTS SEE STS ESTE TET ET ETT TTT TT TTT ET TE TS 


RLSE$REQ MVI RET$FTN,RET$RLSE IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=RLSE,FLC=0,BUFLIST=0, FLTAREA=NOKEEP, X 
MF= (E, CVPL$DEF) 
+ LA 1,CVPL$DEF LOAD PARAMETER REG 1 
+ MVI 6(1),X'10' SET FUNCTION CODE 
+ NI 10(1),B'01111111' RESET CVAF FLAGS OFF 
+ LA 15,0 GET FCL ADDRESS AND 
+ oT 15-166, 1) STORE FCL PTR IN PARM LIST 
+ LA 15.70 GET BUFLIST ADDRESS AND 
+ ST 15,20(,1) STORE BUFLIST PTR IN PARM LIST 
+ Svc 139 . 
LTR R15,R15 IF NO ERROR ON RELEASE REQUEST 
BZ RETURN GO RETURN TO CALLER 
LA R1,RET$RLSE ELSE INDICATE ERROR IN RELEASE 


2 
(EES SESE EEE ES EERE EE SEE ESSERE SESE ES ERE ES ESSER EEE EES SES ESE SES EES SESE SE 
* PLACE ERROR INFORMATION IN THE OUTPUT DATA RETURN AREA 
(EERE EEE EEE EES EEE EEE SESE ES EEE ESSE SES ESE EES EEE ES EEE ESE ESE EE EE EE ESE EE S 
ERR$RET MVC RET$STAT,CVSTAT COPY CVSTAT TO RETURN AREA 

ST R15,RET$RC COPY CVAFFILT'S RETURN CODE 
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* 
Me Re ie 2 2 2 eee ei ee ie ie ie ie ie ee 2 2 ie ie ee ee oe ee 2 2 2 8 2 2 2 2 ee 2 2 ee i ie ae ae a ee KE KK 
* ASSUME R15 = DESIRED RETURN CODE, SET R1 -> DATA RETURN AREA, 


* RESTORE CALLER'S REGISTERS 0, 2-14, AND RETURN TO CALLER 
Oe fe fe oe fe fee ie fe ofc oe fe fe ie fe ake oe fe oie a fe oie fe oe ofc ee fe a ofc oft fe Re Ae ae fe oie fe ofr oie fe fe ode ae fe oie ie ode oe a oie le ake a oie ie ade ae a a ke 2 


RETURN LA R1,RET$AREA R1 -> OUTPUT DATA RETURN AREA 
L R13,SAVEAREA+4 R13 -> CALLER'S REG SAVE AREA 
L R14,12(R13) RESTORE CALLER'S REGISTER 14 
L RO, 20 (R13) RESTORE CALLER'S REGISTER 0O 
LM R2,R12,28(R13) RESTORE CALLER'S REGISTERS 2-12 
BR R14 RETURN TO CALLER 
FLAGS DC X'0OO' LOCAL FLAG BYTE 
FE$RSET EQU X'OO' FLAG RESET VALUE 
FS$LAST EQU x'80' LAST DSCB SET ENCOUNTERED 
* 
LTORG 
=H'1' 
=C'xx! 
=H'4' 
* 
SAVEAREA DC 18F'O' REGISTER SAVE AREA 


* 

PS SSS ESESE SESE SESE SESS SESE SES SESS SS SES SESE STE SSE SE SE SSE RSET ESSE EEE SET SS 
* MAPPING MACROS 

FS SSZEEZESE SESE SESE SESS SETS SESE SE SSE SESE SESS SESE SSES SEES TEESE SEES ESE ES ES ES 


CVPL$MAP ICVAFPL CVPLFSA=YES 
TES E SELES ESE LEE L EE EES SESE LES ESE LESSEE ESSE SETS TTT TTT TST TTT TTT TET TT TS SF 


4% CVAF PARAMETER LIST 

SSE ZEL EEE ELESLE SEE EEE SESE SESE SESE SESSEE SEE SEE ESSE LESSEE SESE SS SEE ESE SEE ES SE SF 
+CVPL$MAP DSECT CVAF PARAMETER LIST 

+ DS OF 

+CVLBL DS CL4 EBCDIC 'CVPL' 

+CVLTH DS H LENGTH OF CVPL 
+CVFCTN DS XL1 FUNCTION BYTE 

+CVDIRD EQU X'O1' CVAFDIR ACCESS=READ 
+CVDIWR EQU x02? CVAFDIR ACCESS=WRITE 
+CVDIRLS EQU X'03' CVAFDIR ACCESS=RLSE 
+CVSEQGT EQU X'04' CVAFSEQ ACCESS=GT 
+CVSEQGTE EQU x05" CVAFSEQ ACCESS=GTEQ 
+CVDMIXA EQU x'06' CVAFDSM ACCESS=IXADD 
+CVDMIXD EQU X'O7' CVAFDSM ACCESS=IXDLT 
+CVDMALC EQU X'08' CVAFDSM ACCESS=ALLOC 
+CVDMRLS EQU x'09' CVAFDSM ACCESS=RLSE 
+CVDMMAP EQU X'OA! CVAFDSM ACCESS=MAPDATA 
+CVVOL EQU X'OB' CVAFVOL ACCESS=VIBBLD 
+CVVRFRD EQU X'0oc! CVAFVRF ACCESS=READ 
+CVVRFWR EQU Xx OD" CVAFVRF ACCESS=WRITE 
+CVFIRD EQU X'OE' CVAFFILT ACCESS=READ 
+CVFIRES EQU X'OF' CVAFFILT ACCESS=RESUME 
+CVFIRLS EQU X'10' CVAFFILT ACCESS=RLSE 
+CVSTAT DS XL1 STATUS INFORMATION (SEE LIST 
+ BELOW) 

+CVFL1 DS XL1 FIRST FLAG BYTE 
+CV1IVT EQU Xx'80' INDEXED VTOC ACCESSED 
+CV1IOAR EQU x! a0" ITOAREA=KEEP 

+CV1PGM EQU x20" BRANCH= (YES , PGM) 
+CVIMRCDS EQU x70" MAPRCDS=YES 

+CV1IRCDS EQU x'08'! IXRCDS=KEEP 

+CV1MAPIX EQU x04" MAP=INDEX 

+CV1IMAPVT EQU x'O2:’ MAP=VTOC 

+CV1IMAPVL EQU X'O1' MAP=VOLUME 

+CVFL2 DS XL1 SECOND FLAG BYTE 
+CV2HIVIE EQU x'8so'! HIVIER=YES 

+CV2VRF EQU X'40! VRF DATA EXISTS 
+CV2CNT EQU X'20' COUNT=YES 

+CV2RCVR EQU x TO! RECOVER=YES 
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+CV2SRCH EQU X'08' SEARCH=YES 

+CV2DSNLY EQU X'04' DSNONLY=YES 

+CV2VER EQU X'02' VERIFY=YES 

+CV2NLEVL EQU X'O1' OUTPUT-NEW HIGHEST LEVEL VIER 
+* CREATED 

+CVFL3 DS XL1 THIRD FLAG BYTE 

+CV3FILT EQU X'80' FLTAREA=KEEP 

+CV3IXERR EQU X'40' INDEX ERROR FOUND 

+ DS XL1 RESERVED 

+CVUCB DS A UCB ADDRESS 

+CVDSN DS A DATA SET NAME ADDRESS 

+ ORG CVDSN 

+CVFCL DS A FILTER CRITERIA LIST ADDRESS 
+CVBUFL DS A BUFFER LIST ADDRESS 

+CVIRCDS DS A INDEX VIR'S BUFFER LIST ADDRESS 
+CVMRCDS DS A MAP VIR'S BUFFER LIST ADDRESS 
+CVIOAR DS A I/O AREA ADDRESS 

+CVDEB DS A DEB ADDRESS 

+CVARG DS A ARGUMENT ADDRESS 

+CVSPACE DS A SPACE PARAMETER LIST ADDRESS 
+CVEXTS DS A EXTENT TABLE ADDRESS 

+CVBUFL2 DS A NEW VRF VIXM BUFFER LIST ADDR 
+CVVRFDA DS A VRF DATA ADDRESS 

+CVCTAR DS A COUNT AREA ADDRESS 

+CVFSA DS A FILTER SAVE AREA ADDRESS 
+CVPLNGTH EQU *-CVPL$MAP 

+* VALUES OF CVSTAT 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 


FCL$¢MAP ICVFCL 
POSES SELES LS LSS SESE ESE SES SESS ST SS SS SCS SETS ESE TST C SS TST TST TST eT Se eT ee 


+* FILTER CRITERIA LIST 
TES ESE SELES ESTES ESET ESE SESE SESE SEES SESE TSS ESET ESTE LSS ELECTS SEE ST Se 








+FCL$MAP DSECT CVAF FILTER CRITERIA LIST 
+FCLID DS CL4 EYE CATCHER 'FCL ' 

+FCLCOUNT DS H NUMBER OF DSN'S IN LIST 
+FCLDSCBR DS H NUMBER OF DSCB'S RETURNED 
+FCLIFLAG DS x REQUEST FLAG BYTE 

+FCLILIST EQU X'80' LIST CONTAINS FULLY QUALIFIED 
++ DATA SET NAMES 

+FCLIORDR EQU  X'4O' CALLER REQUESTS FCL ORDER 
+FCL2FLAG DS X STATUS FLAG BYTE 

+FCL2SEQ EQU  X'80' SEQUENTIAL VTOC ACCESS SELECTED 
+FCL2SDIR EQU  X'4O' SEQUENTIAL VTOC ACCESS REQUIRED 
+* AT LEAST ONE DIRECT DSCB READ 
+FCLDRSV DS XL6 RESERVED 

+FCLHDEND EQU * DSN ENTRIES DIRECTLY FOLLOW 
+FCLHDLEN EQU  *-FCLID LENGTH OF FCL HEADER 

4% 

+ DSECT MAP OF EACH DSN ELEMENT 
+FCLDSN _CL8 DATA SET NAME INFORMATION 

+ ORG FCLDSN 

+FCLDSNST DS X STATUS OF THIS DATA SET NAME 
+FCLSTOO EQU  x'0O' DSN REMAINS TO BE PROCESSED 
+FCLSTO1 EQU  X'01' DSCB(S) HAVE BEEN RETURNED 

+* FOR FCLSTO2 THROUGH FCLSTO5 -- CVAFFILT WILL NOT RETURN ANY 

+* DSCB(S) FOR THE ASSOCIATED DSN ------------------ 

+FCLSTO2 EQU  X'02' DSN NOT FOUND 

+FCLSTO3 EQU  X'03! ANOMALY FOUND IN DSCB(S) 
+FCLSTO4 EQU  xX'04' ANOMALY FOUND IN CVAFFILT 
+FCLSTO5 EQU  X'05' NUMBER OF DSCBS FOR THIS DSN 
+* IS GREATER THAN THE TOTAL 
+* NUMBER OF BFLE PROVIDED 

+% 

+FCLDSNLG DS X DATA SET NAME LENGTH 


nee tena OE Ns mam Poem, atm eT t= 
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+FCL3FLAG DS X FLAG BYTE 





+FCL3UPDT EQU  xX'80' THIS ELEMENT WAS PROCESSED a 
+* BY THIS INVOCATION \ 
+FCLDSNRV DS x RESERVED 

+FCLDSNA DS F DATA SET NAME ADDRESS 

+FCLDSNEL EQU  *-FCLDSN LENGTH OF DSN INFO ENTRY 


BFL$MAP ICVAFBFL 
PES E LE LE LE LES EEE EEE ESE SES ET SSE TESTES SESE TS SS ESET EEE S SES TT SET ETE STE SE EF 


+* BUFFER LIST HEADER 
Sth ee ee e ee e ee ee eee ee ee EERE EE EE SEES SSS SEE SEES ES ESSE SESE SESE SES EE SESE SE FS 
+BFL$MAP DSECT BUFFER LIST HEADER 
+ DS OF 
+BFLHNOE DS XL1 NUMBER OF ENTRIES 
+BFLHFL DS XL 1 KEY AND FLAG BYTE 
+ ORG BFLHFL 
+BFLHKEY DS XL 1 PROTECT KEY (FIRST 4 BITS) 
+BFLHVIR EQU X'08' | ‘BUF. LIST ENTRIES DESCRIBE VIRS 
+BFLHDSCB EQU X'O4' BUF. LIST ENTRIES DESCRIBE DSCBS 
+ DS XL1 RESERVED 
+BFLHSP DS XL1 SUBPOOL OF BUF. LIST/BUFFERS 
+BFLHFCHN DS A FORWARD CHAIN PTR TO NEXT BUF. 
+%* LIST 
+BFLHLN EQU *-—-BFLSMAP LENGTH OF BUFFER LIST HEADER 
SSE SEE SESE SES EE SEES ESTES EEE LESSEE EES ESSE SSSR ESSERE ESLER ESS ESE SE SEE ES EE SS 
+% BUFFER LIST ENTRY 
SSR e EEE EEE ESE EEE SEE ESSE SESE EEE SESE EEE SEE EES SEES ERE EE EES EES SESE EES ESE ES OE OS 
+BFLE DSECT BUFFER LIST ENTRY 
+ DS OF 
+BFLEFL DS XL 1 BUFFER LIST ENTRY FLAG 
+BFLERBA EQU Xx'80' ARGUMENT IS RBA 
+BFLECHR EQU X'40' ARGUMENT IS CCHHR 2 
+BFLETTR EQU X'20' ARGUMENT IS TTR 
+BFLEAUPD EQU X'10' CVAF UPDATED ARGUMENT FIELD ae 
+BFLEMOD EQU x'O8' DATA IN BUF. HAS BEEN MODIFIED ~~ 
+BFLESKIP EQU X'O4' SKIP THIS ENTRY 
+BFLEIOER EQU Kr OZ" I/O ERROR 
+ DS XL1 RESERVED 
+BFLELTH DS XL 1 LENGTH OF DSCB BUFFER OR 
+%* LENGTH OF VIR DIVIDED BY 256 
+BFLEARG DS XL5 ARGUMENT OF VIR OR DSCB_ (CCHHR) 
+ ORG BFLEARG+1 
+BFLEATTR DS XL3 'TTR' OF ARGUMENT 
+ ORG BFLEARG+1 
+BFLEARBA DS XL4 "RBA' OF ARGUMENT 
+BFLEBUF DS A BUFFER ADDRESS 
+BFLELN EQU *-BFLE LENGTH OF A BUFFER LIST ENTRY 
PUSH PRINT 


PRINT NOGEN 
DSCB$MAP DSECT 


IECSDSL1 (1) USE FORMAT 1 DSCB MAPPING TO GET BUFFER SIZE 
DSCB$SIZ EQU *-TECSDSL1 LENGTH OF FULL DSCB 
POP PRINT 


PEE ELLE LE LE LESSEE SSE SELLE STE E SES ESET EL ESET SELES EE SEL ELLE SLES ELE EEE ET ee 
* SPACE ALLOCATION FOR CVPL, FCL, BFL, AND DSCB BUFFERS 

PEER SESE LE LES ELE SEES EES ELSES EEL SELES EL EE TEES EE SE EES SES ES EEE EES EL EEE SE SE 
EXAMPLE3 CSECT , CONTINUATION OF CSECT 

CVPL$DEF CVAFFILT MF=L, BRANCH=NO, FLTAREA=KEEP 





+ CNOP 0O,4 

+CVPL$DEF EQU * 

+ DC CL4'CVPL' EBCDIC 'CVPL' 

+ DC AL2 (ICV11E-CVPL$DEF) LENGTH OF CVPL 

+ DC XL1'OE' FUNCTION CODE 

+ DC XL1'00' STATUS INFORMATION 
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+ DC B'OQOOO00000! FIRST FLAG BYTE 

+ DC B'OOOO00000' SECOND FLAG BYTE 

+ DC B'10000000' THIRD FLAG BYTE 

+ DC X'0O' RESERVED 

+ DC A(0) UCB ADDRESS 

+ DC A(0) FILTER CRITERIA LIST ADDRESS 

+ DC A(0) BUFFER LIST ADDRESS 

+ DC A(0) INDEX VIR'S BUFFER LIST ADDRESS 
+ DC A(0) MAP VIR'S BUFFER LIST ADDRESS 

+ DC A(0) I/O AREA ADDRESS 

+ DC A(0) DEB ADDRESS 

+ DC A(Q) ARGUMENT ADDRESS 

+ DC A(0) SPACE PARAMETER LIST ADDRESS 

+ DC A(0) EXTENT TABLE ADDRESS 

+ DC A(0) NEW VRF VIXM BUFFER LIST ADDRESS 
os DC A(0O) VRF DATA ADDRESS 

+ DC A(0) COUNT AREA ADDRESS 

+ DC A(0) FILTER SAVE AREA ADDRESS 
+ICVI1E EQU * END OF CVPL 


FCL$ID DC CL4'FCL ' 

FCL$DEF DS (FCLHDLEN+FCLDSNEL) X FCL HEADER AND ONE FCL ELEMENT 
FCL$SIZE EQU *-FCLE$DEF 

* DEFINE A CVAF BUFFER LIST WITH N BUFFER LIST ELEMENTS 

BFLH$DEF DS (BFLHLN) X BUFFER LIST HEADER 

BFLE$DEF DS (BFLE$N*BFLELN) X N BUFFER LIST ELEMENTS 

BFL$SIZE EQU *-BFLH$DEF 

* DEFINE N FULL DSCB BUFFERS 





DSCB$DEF DS (BFLE$N*DSCB$SIZ) X 
PEE EEE ELE LESS ESE SERS ESSE SESE SSE SE SSE SESE ESET ESS EELS SSE SESE SESE ESSE SE SEE SE SE FE 
* OUTPUT DATA RETURN AREA 
oe AK kK KK OK 3 KK KK OK OK KK KK KK KK kK KK KK KK KK OK KK OK KK OK KK KK OK KK OK KK KOK OK KO KK OK KK KK kK KK KK HK 
DS OF 
RET$AREA DS OXL20 OUTPUT DATA RETURN AREA 
RET$F1 DC F'O! COUNT OF FORMAT 1 DSCBS RETURNED BY CVAFFILT 
RET$F2 DC F'O! COUNT OF FORMAT 2 DSCBS RETURNED BY CVAFFILT 
RET$F3 DC F'0! COUNT OF FORMAT 3 DSCBS RETURNED BY CVAFFILT 
* 
RET$ERR DS OXL8 IF NO ERROR CONDITION WAS ENCOUNTERED THEN 
* REGISTER 15 = ZERO ON RETURN 
* OTHERWISE THE FOLLOWING INFORMATION IS PROVIDED 
RET$FTN DC x'00' IDENTIFICATION OF CVAFFILT SUBFUNCTION 
RET$READ EQU x'O1' CVAFFILT ACCESS=READ 
RET$RSUM EQU  xX'02' CVAFFILT ACCESS=RESUME 
RET$RLSE EQU  xX'03' CVAFFILT ACCESS=RLSE 
DC XL2'00' UNUSED 
RET$STAT DC x'00' COPY OF CVSTAT FROM CVAFFILT 
RET$RC DC F'O! COPY OF THE RETURN CODE FROM CVAFFILT 
END 


Example 4: Using the CVAFSEQ Macro with an Indexed VTOC 


This example uses the CVAFSEQ macro to count the number of ISAM data sets 
whose data set names are within the range defined by two supplied data set 
names. The addresses of the two data set names are supplied to the program in 
registers 6 and 7, labeled RDSN1 and RDSN2, respectively. The address of a 
DEB open to the VTOC is supplied in register 4, labeled RDEB. 
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The CVAF parameter list is expanded by a list form of the CVAFSEQ macro. ie 
ACCESS=GTEQ is specified on the list form of the macro and is, therefore, not f ~ 
coded in the first execution of the CVPL. Subsequent executions of the CVPL 5 a 
(at label RELOOP) specify ACCESS=GT. 


End of data is tested by comparing the CVSTAT field to the value of STAT032, 
which is an equate in the ICVAFPL mapping macro. 


The count of ISAM DSCBs matching the data set name criterion is returned in 
register 15, unless an error is encountered, in which case a negative 1 is returned 
in register 15. 
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EXAMPLE4 CSECT 
STM 14,12,12(13) 


( 7 BALR 12,0 

a USING *, 12 
ST  13,SAVEAREA+4 
LA  RWORK, SAVEAREA 
ST  RWORK,8(,13) 
LR «13, RWORK 


(Eee eee te eee eee eee ES ESE SES EEE SSSR SEES ESSE SSE SESE SESE RES ES ES SF 
* 

* REGISTERS 

* 

(eee eee te ee eS SEE EEE EERE SES EE SES ESSE SSS ESSE SESE ESE SESE SES EE SF 


REG1 EQU 1 REGISTER 1 

RWORK EQU 3 WORK REGISTER 

RDEB EQU 4 DEB ADDRESS 

RDSN1 EQU 6 ADDRESS OF DATA SET NAME 1 
RDSN2 EQU 7 ADDRESS OF DATA SET NAME 2 
REG15 EQU 15 RETURN CODE REGISTER 15 


22 A A A A A A I RR ER 

* 

‘ COUNT THE NUMBER OF ISAM DATA SETS WHOSE DATA SET NAMES ARE 
* BETWEEN DSN1 AND DSN2 INCLUSIVELY. 

* RDSN1 CONTAINS ADDRESS OF DSN1. 

* RDSN2 CONTAINS ADDRESS OF DSN2. 

* ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

* 
* 


He A I I A A I A I A I I AA A OR RK 
XC BUFLIST (BFLHLN+BFLELN) ,BUFLIST ZERO BUFFER LIST 





OL BFLHFL, BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHNOE, 1 ONE BUFFER LIST ENTRY 
LA RWORK ,DS1FMTID ADDRESS OF DSCB BUFFER 
ST RWORK , BFLEBUF PLACE IN BUFFER LIST 
MVI BFLELTH,DSCBLTH DATA PORTION OF DSCB READ - DSN * 
SUPPLIED IN CVPL 
MVC DS1DSNAM,0(RDSN1) MOVE IN STARTING DATA SET NAME TO * 
WORKAREA 
XR RWORK , RWORK ZERO COUNT 
CVAFSEQ DEB=(RDEB) , FIND FIRST DATA SET WHOSE DATA SET * 
BUFLIST=BUFLIST, NAME IS GREATER THAN OR EQUAL TO * 
MF=(E,CVPL) THAT OF DSN1 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ ST RDEB, 36(,1) STORE DEB PTR IN PARM LIST 
+ SVC 139 
LOOP EQU * LOOP UNTIL END OF DATA OR DATA SET * 
NAME GREATER THAN DSN2 
USING CVPL,REG1 ADDRESSABILITY TO CVPL 
LTR REG15,REG15 ANY ERROR 
BZ TESTDSN BRANCH IF NOT-CHECK DSN LIMIT 


(Pee EERE EES ESSERE EE LES ESS SS SESS SERS SESS ESSE SEE EEE EE SSE EEE SE ESS 
* 

* DETERMINE WHAT ERROR IS 

* 

Lee EEE EEE EEE ESE SESE SESE EES ESE SSS SELES EEE EEE EEE EEE ES EE ESE EE ES 


c REG15,ERROR4 IS RETURN CODE 4 

BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STATO32 IS IT END OF DATA? 

BNE OTHERERR- BRANCH IF NOT 

DROP REG1 ADDRESSABILITY TO CVPL NOT NEEDED 


(Eee kee eke ES RE EE SEE EE EEE EE EEE EE SEE EE ESE EEE SEES EES EES ES SE 
* 

* END OF DATA 

* 

PEPE eee EEE EEE EE SEE EE REE SEE EERE LES EEE SESE SEES ES EEE SESS ES ESE ES 
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B RELEASE RELEASE CVAF RESOURCES AND RETURN 
TESTDSN EQU * IS DATA SET NAME GREATER THAN DSN2 Ue =a 


CLI DS1FMTID,C'1' IS THIS A FORMAT 1 DSCB? ff ; 
BNE CKLAST BRANCH IF NO. CAN NOT BE ISAM. ee? 
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED? 
BNH TESTIS BRANCH IF NO-TEST FOR ISAM 
B RELEASE RELEASE CVAF RESOURCES AND RETURN 
TESTIS EQU #* ONLY COUNT ISAM 
TM DS1DSORG,DS1DSGIS IS DATA SET ISAM 
BZ  CKLAST BRANCH IF NO-DO NOT COUNT IT 
LA  RWORK,1(,RWORK) INCREMENT COUNT BY ONE 
CKLAST EQU * CHECK IF LAST DATA SET NAME (DSN2) 
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED? 
BNH RELOOP BRANCH IF NO-READ NEXT ONE 
B RELEASE RELEASE CVAF RESOURCES AND RETURN 
RELOOP EQU * READ NEXT DSCB 
CVAFSEQ ACCESS=GT,MF=(E,CVPL) GET DSCB WITH DATA SET NAME * 
GREATER THAN THE ONE LAST READ 
+ LA 1,CVPL LOAD PARAMETER REG 1 
x MVI 6(1),xX'04' SET FUNCTION CODE 
re svc 139 
B LOOP CHECK RESULTS OF CVAFSEQ 
OTHERERR EQU * UNEXPECTED ERROR 
Lee eee EES ESSE ES SESE SSS SSL SS SESS SS ESSE SSS SSS ESS ESE SEES ES SEE E SS 
* 
* UNEXPECTED ERROR PROCESSING 
* 
OK He ake oe ae he ake ok Ke oe ok oe oe oe ok ok ok ok i ok oie Ke oe oi Ko i oe ok ok oe KK Ke ok ok ok ok ie ok Ke ok ok ok Ke ok Ke ok ok ok ok ok ok Ke oe ok ok ok ok ok 
LA  RWORK,1(0,0) ONE IN RWORK 
LNR RWORK,RWORK SET NEGATIVE COUNT INDICATING ERROR 
RELEASE CVAFDIR ACCESS=RLSE, RELEASE CVAF BUFFERS/IOAREA * 
BUFLIST=0, DO NOT RELEASE USER BUFFER LIST * 
IXRCDS=NOKEEP, RELEASE CVAF VIER BUFFERS x wae, 
MF=(E,CVPL) RELEASE CVAF I/O AREA 
+RELEASE EQU- #* ae 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ MVI 6(1),X'03' SET FUNCTION CODE 
+ NI 8(1),B'11110111' RESET CVAF FLAGS OFF 
+ LA 15,0 GET BUFLIST ADDRESS AND 
+ ST 15,20(,1) STORE BUFLIST PTR IN PARM LIST 
+ SVC 139 
LR  REG15,RWORK CURRENT COUNT IS RETURN CODE 
12 13, SAVEAREA+4 
RETURN (14,12) ,RC=(15) RETURN CURRENT COUNT 
+ 9 44,12 (13,0) RESTORE REGISTER 14 
+ LM 0,12,20(13) RESTORE THE REGISTERS 
+ BR 14 RETURN 
ERROR4 DC F'4' ERROR RETURN CODE 4 
BUFLIST ICVAFBFL DSECT=NO BUFFER LIST 
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tt tee eee eee ee EERE EEE EERE EE ESE EE EEE EERE SEE EEE EES SESE ESS SEES ES SEE SE 


+% 


BUFFER LIST HEADER 


Tt thee eee kee eee ke SS EE EES EEE ESE EEE SEE EEE SE ESE SESE SS SEER SESE E EEE SES SS SE 


+BUFLIST 
+BFLHNOE 
+BFLHFL 

+ 
+BFLHKEY 
+BFLHVIR 
+BFLHDSCB 
+ 
+BFLHSP 
+BFLHFCHN 
+ 
+BFLHLN 


DS 
DS 
DS 
ORG 
DS 
EQU 
EQU 
DS 
DS 
DS 


EQU 


OF 

XL 1 
XL1 
BFLHFL 
XL1 
X'08' 
X'O4' 
XL 1 
XL 1 

A 


*-BUFLIST 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 


PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
FORWARD CHAIN PTR TO NEXT BUF. 
LIST 

LENGTH OF BUFFER LIST HEADER 


“RRR RGR GIGI GGG GGG IGG GGG GIG GGG a a a a kak 


+% 


BUFFER LIST ENTRY 


ttt tte ee Ee EE REE EEE EEE EES E SEE EE SESE EEE EEE RS SER EERE EES ESSE SE SE ES 


+BFLE 
+BFLEFL 
+BFLERBA 
+BFLECHR 
+BFLETTR 
+BFLEAUPD 
+BFLEMOD 
+BFLESKIP 
+BFLEIOER 
+ 
+BFLELTH 
+% 
+BFLEARG 
+ 
+BFLEATTR 
+ 
+BFLEARBA 
+BFLEBUF 
+BFLELN 


+IECSDSL1 
+IECSDSF1 
+DS1DSNAM 
+DS1FMTID 
+DS1DSSN 
+DS1VOLSQ 
+DS1CREDT 
+DS1EXPDT 
+DS 1NOEPV 
+DS 1NOBDB 
+ 

+ 
+DS1SYSCD 
+ 

+DS 1DSORG 





DS 
DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 

DS 


DS 
ORG 
DS 
ORG 
DS 
DS 
EQU 


OF 
XL 1 
X'80' 
X'40' 
X'20' 
ee 0 
X'O8' 
X'04' 
xO 2; * 
XL 1 
XL1 


XL5 
BFLEARG+1 
XL3 
BFLEARG+ 1 
XL4 

A 

*-BFLE 


ITECSDSL1 (1) 


EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 


DS 
DS 
DS 
DS 


a 


IECSDSL1 
CL44 

CL1 

CL6 

XL2 

XL3 

XL3 

XL1 

XL1 


XL 1 
CL13 
XL7 
XL2 


BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 
ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 
DATA IN BUF. HAS BEEN MODIFIED 
SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB (CCHHR) 


'TTR' OF ARGUMENT 


"RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FORMAT 1 DSCB DATA SET NAME AND * 
BUFFER 
FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 

RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 
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+% 
+DS1DSGIS 
+% 
+DS1DSGPS 
+% 
+DS1DSGDA 
+DS 1DSGCX 
+% 

+% 
+DS1DSGPO 
+DS 1DSGU 
+% 

+% 

+% 

43k 
+DS1DSGGS 
+DS 1DSGTX 
+DS 1DSGTQ 
$e” 
+DSTACBM 
+DS1DSGTR 
+% 

+% 
+DS1RECFM 
+DS10PTCD 
+DS 1BLKL 
+DS1LRECL 
+DS1KEYL 
+DS1RKP 
+DS 1DSIND 
+DS 1SCALO 
+DS1LSTAR 
+DS 1TRBAL 
+ 
+DS1EXT1 
+% 

+% 

+% 

+% 

+DS 1EXT2 
+DS1EXT3 
+DS1PTRDS 
+DS 1END 
DSCBLTH 
SAVEAREA 
CVPL 


EQU x'80! 
EQU xX'4O! 
EQU  xX'20' 
EQU xX'10' 
EQU xX'O8' 
EQU xX'0O4' 
EQU  x'Q2' 
EQU x'O1' 
EQU  xX'8O' 
EQU  xX'4O' 
EQU  X'20! 
EQU x'10' 
EQU x'O8' 
EQU xX'O4' 
EQU xX'02' 
EQU xX'O1' 
DS XL1 
DS XL1 
DS XL2 
DS XL2 
DS XL1 
DS XL2 
DS XL1 
DS XL4 
DS XL3 
DS XL2 
DS XL2 
DS XL10 
FIRST BYTE 


SECOND BYTE 


FIRST BYTE OF DS1DSORG 


IS - INDEXED SEQUENTIAL 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 
ORGANIZATION 

DA - DIRECT ORGANIZATION 

CX - BTAM OR QTAM LINE GROUP 
RESERVED 

RESERVED 

PO - PARTITIONED ORGANIZATION 
U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 


SECOND BYTE OF DS1DSORG 


THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 


DS 
DS 
DS 
EQU 
EQU 
DS 


XL10 
XL10 


XL5 
* 


CVAFSEQ ACCESS=GTEQ, 
IXRCDS=KEEP, 
DSN=DS1DSNAM, 
BUFLIST=BUFLIST, 


CNOP 
EQU 
DC 
DC 
DC 
DC 
DC 
DC 


MF=L 
0,4 
* 


CL4'CVPL' 
AL2 (ICV10E-CVPL) 


XL1'0O5' 
XL1'OO' 


B'00001000' 
B'00000000' 
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GS - GRAPHICS ORGANIZATION 
TX - TCAM LINE GROUP 

TQ - TCAM MESSAGE QUEUE 
RESERVED 

ACCESS METHOD CONTROL BLOCK 
TR - TCAM 3705 

RESERVED 

RESERVED 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 
SECONDARY ALLOCATION 





aO1TA 
aOTA 


AaOTA 
aOTA 
aOTA 
aO1A 
aOTA 
AaOTA 


aO1A 
aO1A 
a01A 
aO1A 
@a01A 
a01A 
aO1A 
a01A 


LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 


RESERVED 

FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 


POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 


SAVE AREA 
READ DSCB WITH DSN >= 


SUPPLIED DATA SET NAME 


EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
FIRST FLAG BYTE 
SECOND FLAG BYTE 


*-TECSDSL1-L'DS1DSNAM LENGTH OF DATA PORTION OF DSCB 
18F 
SUPPLIED DSN * 
KEEP VIERS IN STORAGE DURING CALLS 


* 

















++ teteteteteeeeeettest 


ICV10E 


CVPLMAP 


A(DS1DSNAM) 


DC H'O! 
DC A(0) 
DC 

DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
DC A(0) 
EQU* 
ORG CVPL 


ICVAFPL DSECT=NO 


RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 


EXPAND MAP OVER LIST 
CVPL MAP 


PEEEKKKKKKKK KKK KKK KKK KK KKK KK KK KK KK HK KK KK HK HK KK KK KO KK KK KK KK HK KK KK HK KK KK KK HK KK HK 


+% 


CVAF PARAMETER LIST 


+ KKK KKK KK KK KK KK KK KK KK KK KK KK HK KK HK KK KK HK KK KK KK KK eK KK KK eK KK KK KE KK KK 


+CVPLMAP 
+CVLBL 
+CVLTH 
+CVFCTN 
+CVDIRD 
+CVDIWR 
+CVDIRLS 
+CVSEQGT 
+CVSEQGTE 
+CVDMIXA 
+CVDMIXD 
+CVDMALC 
+CVDMRLS 
+CVDMMAP 
+CVVOL 
+CVVRFRD 
+CVVRFWR 
+CVSTAT 

+ 

+CVFL1 
+CVIIVT 
+CV1IOAR 
+CV1PGM 
+CV1MRCDS 
+CV1IRCDS 
+CV1MAPIX 
+CV1MAPVT 
+CV1MAPVL 
+CVFL2 
+CV2HIVIE 
+CV2VRF 
+CV2CNT 
+CV2RCVR 
+CV2SRCH 
+CV2DSNLY 
+CV2VER 
+CV2NLEVL 
+* 

+ 


DS 

DS 

DS 

DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 


DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


DS 


OF 
CL4 
H 

XL 1 
X'0O1' 
X'O2' 
X'03' 
X'O4' 
X'0O5' 
X'06' 
X'0O7' 
X'08' 
Xx'09' 
X'OA' 
X'OB' 
X'OC' 
X'OD' 
XL1 


XL1 

X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 
X'O1' 
XL1 

X'80" 
X'40' 
X'20' 
X'10' 
X'08' 
X'O4' 
X'02' 
X'01' 


H 


CVAF PARAMETER LIST 
EBCDIC 'CVPL' 

LENGTH OF CVPL 
FUNCTION BYTE 

CVAFDIR ACCESS=READ 
CVAFDIR ACCESS=WRITE 
CVAFDIR ACCESS=RLSE 
CVAFSEQ ACCESS=GT 
CVAFSEQ ACCESS=GTEQ 
CVAFDSM ACCESS=IXADD 
CVAFDSM ACCESS=IXDLT 
CVAFDSM ACCESS=ALLOC 
CVAFDSM ACCESS=RLSE 
CVAFDSM ACCESS=MAPDATA 
CVAFVOL ACCESS=VIBBLD 
CVAFVRF ACCESS=READ 
CVAFVRF ACCESS=WRITE 
STATUS INFORMATION (SEE LIST * 
BELOW) 

FIRST FLAG BYTE 
INDEXED VTOC ACCESSED 
IOAREA=KEEP 
BRANCH= (YES , PGM) 
MAPRCDS=YES 
IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 
HIVIER=YES 

VRF DATA EXISTS 
COUNT=YES 

RECOVER=YES 
SEARCH=YES 
DSNONLY=YES 
VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 
CREATED 

RESERVED 
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+CVUCB DS A UCB ADDRESS 

+CVDSN DS A DATA SET NAME ADDRESS 

+CVBUFL DS A BUFFER LIST ADDRESS 

+CVIRCDS DS A INDEX VIR'S BUFFER LIST ADDRESS 
+CVMRCDS DS A MAP VIR'S BUFFER LIST ADDRESS 
+CVIOAR DS A I/O AREA ADDRESS 

+CVDEB DS A DEB ADDRESS 

+CVARG DS A ARGUMENT ADDRESS 

+CVSPACE DS A SPACE PARAMETER LIST ADDRESS | 
+CVEXTS DS A EXTENT TABLE ADDRESS 

+CVBUFL2 DS A NEW VRF VIXM BUFFER LIST ADDR 
+CVVRFDA DS A VRF DATA ADDRESS 

+CVCTAR DS A COUNT AREA ADDRESS 

+CVPLNGTH EQU *-CVPLMAP 

+* VALUES OF CVSTAT 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END ; | 
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Example 5: Using the CVAFSEQ Macro with a Nonindexed VTOC 





EXAMPLE5 CSECT 
OTM 
BALR 
USING 





This example reads as many as five DSCBs in physical-sequential order. The 
address of the UCB is supplied to the program in register 5 (labeled RUCB). 
The address of a parameter list is supplied in register 4 (labeled RLIST). The 
first word of the parameter list contains the address of a 5-byte field. On entry, 
this field is set to zero if no previous DSCBs have been read; otherwise, the field 
is set to the CCHHR of the last DSCB read. This 5-byte field is supplied by the 
caller of this program and is not modified by this program. 


The remainder of the parameter list consists of one or more 2-word entries, to a 
maximum of five 2-word entries. The first word of each entry contains the 
address of a 140-byte DSCB buffer. The second word contains the address of a 
5-byte field that is to contain the CCHHR of the DSCB. 


A buffer list with five buffer list entries is contained in the program. The 
ICVAFBFL macro generates the buffer list header and one buffer list entry. 
The remaining buffer list entries are generated following the ICVAFBFL macro. 


The CVAFSEQ macro is used once in the program to read as many DSCBs as 
there are 2-word entries in the parameter list. The buffer list header field 
BFLHNOE is initialized with the number of buffer list entries that CVAFSEQ is 
to process. The number matches the number of 2-word entries in the parameter 
list supplied to this program. 


After the CVAFSEQ call, the CCHHR for each DSCB read is moved from the 
buffer list entry field BFLEARG to the field whose address is supplied by the 
caller of the program. If the BFLEARG field is zero, the previous DSCB read 
was the last in the VTOC. 


The BFLEARG in the first buffer list entry is initialized with the CCHHR 
supplied by the caller: its address is the third word in the parameter list. This 
CCHHR serves as the starting place for the CVAFSEQ call. DSCBs with a 
CCHHR greater than the supplied CCHHR are read. 


This program must be APF authorized. 


14,12,12(13) 
12,0 

*,12 
13,SAVEAREA+4 
RWORK , SAVEAREA 
RWORK, 8(, 13) 
13,RWORK 
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TTT TTT ETITE TILL TCI TTT 
* 


* REGISTERS - 
* Se’ 
EERE EEE EEE EE EES EEE EES ESE LES ESSE ES ESET ES EEE SEE RES EEE EE ES OS ES 
REG1 EQU 1 REGISTER 1 
RWORK EQU 3 WORK REGISTER 
RLIST EQU 4 ADDRESS OF PARM LIST 
RUCB EQU 5 UCB ADDRESS 
RCURRENT EQU 6 CURRENT ENTRY IN PARM LIST 
RBLE EQU 7 CURRENT BUFFER LIST ENTRY 
RCOUNT EQU 8 COUNT OF ENTRIES IN BUFFER LIST 
REG15 EQU 15 RETURN CODE REGISTER 15 
PREPRESS EEE EEE EE EEE EEE EEE EE SEE ESE EEE ESE EEE ES EE ESE SEE ES EE SS 
* 
” READ UP TO 5 DSCBS. 
. RUCB CONTAINS ADDRESS OF UCB. 
ag RLIST CONTAINS ADDRESS OF PARAMETER LIST. 
* WORD O = ADDRESS OF CCHHR OF LAST DSCB READ. THIS DSCB IS 
. NOT TO BE READ 
* WORD 1 = ADDRESS OF DSCB BUFFER. 
* WORD 2 = ADDRESS OF CCHHR OF DSCB READ. 
- WORD1 AND WORD2 REPEATED UP TO 4 TIMES. 
* HIGH ORDER BIT OF WORD 2 SET TO ONE FOR LAST ENTRY. 
a 
PEPE EE EEE EEE EEE EEE EEE EERE SEE ESE SEE EE EE EEE EEE EEE EEE EEE EE EOS OE 
USING LIST,RLIST ADDRESSABILITY TO PARM LIST 
XC BFLHDR (BFLHLN+5*BFLELN) ,BFLHDR ZERO BUFFER LIST WITH * 
5 BUFFER LIST ENTRIES 
OI BFLHFL, BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
LA RCURRENT, LISTPRMS FIRST DOUBLEWORD ENTRY IN PARM LIST 
USING LISTPRMS , RCURRENT USING ON DOUBLEWORDS | 
LA RBLE, BFLE FIRST BUFFER LIST ENTRY : | wer 
USING BFLE,RBLE | CO 
L RWORK, LISTSTRT ADDRESS OF. STARTING CCHHR | sae 
MVC BFLEARG, 0 (RWORK) MOVE STARTING CCHHR INTO FIRST * 
BUFFER LIST ENTRY | 
XR RCOUNT , RCOUNT | ZERO COUNT | 
BUFLOOP EQU *. PUT BUFFER ADDRESSES IN BUFFER LIST * 
ENTRIES 
LA RCOUNT, 1 (, RCOUNT ) INCREMENT COUNT 
L RWORK, LISTBUF ~ADDRESS OF DSCB BUFFER 


ST RWORK, BFLEBUF-BFLE(,RBLE) PLACE IN BUFFER LIST 
MVI BFLELTH-BFLE(RBLE) ,DSCBLTH FULL DSCB READ 


TM LISTLAST, LASTBIT IS IT LAST ENTRY IN LIST 

LA RCURRENT, LISTNEXT INCREMENT TO NEXT ENTRY IN LIST 

LA RBLE,BFLELN(,RBLE) | INCREMENT TO NEXT BUFFER LIST ENTRY 
BZ BUFLOOP LOOP TO PUT NEXT BUFFER IN BFLE 

STC RCOUNT, BFLHNOE SET NUMBER OF ENTRIES IN BUFFER * 


LIST HEADER 
DROP RCURRENT, RBLE 
PEP EEE ELSE EEE ELE EEE SESE EEE EEE SESE EEE SEE E SEES ESTEE ETE EET ES EF 
* a 


* READ UP TO 5 DSCBS WHOSE CCHHR IS GREATER THAN THE CCHHR IN 


* THE FIRST BUFFER LIST ENTRY 
* 


A He He Ke Ke He He eK ee eo KK KK KK KK KK HK KK KK KKK KK KK KK KK KK KK KK KK KKK KKK 
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+ 


++++++4 


CVAFSEQ UCB=(RUCB), 
BRANCH=YES, 
MF=(E,CVPL) 

LA 1,CVPL 


ST RUCB, 12(,1) 


L 15,16 

L 15,328(,15) 
L tee leo: Tn) 
L 15,0, 15) 
BALR 14,15 


USING CVPL,REG1 
LTR REG15,REG15 
BZ MOVECHR 


CALL CVAF * 
BRANCH ENTER * 


LOAD PARAMETER REG 1 


STORE UCB PTR IN PARM LIST 
LOAD THE CVT 
LOAD VS1/VS2 COMMON EXTENSION2 
LOAD THE CVAF TABLE ADDRESS 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESSABILITY TO CVPL 
ANY ERROR 
BRANCH IF MOVE IN CCHHRS 


EE eee eee eee EEE ES SEE ESE EEE ESE SESE SESS SSE EE SESE EEE EEE ESE SE EE SE FS 


* 
* 
* 


DETERMINE WHAT ERROR IS 


SEER EEE EES EEE EEE EES ESSE EEE EEE SES SEE SESS SESE EES EERE ESE SEES EE EE FE 


+ 
+ 


Cc REG15, ERROR4 
BNE OTHERERR 

CLI CVSTAT,STATO32 
BNE OTHERERR 

DROP REG1 


IS RETURN CODE 4 

BRANCH IF NOT 4 

IS IT END OF DATA? 

BRANCH IF NOT 

ADDRESSABILITY TO CVPL NOT NEEDED 


(EEE Ee Eee EEE SESE EEE REE ES ESSE EES SS ESE SE EES SES SESE SEE ES EE EE SE FS 


* 
Es 
* 
* 


DETERMINE IF ANY DSCBS HAVE BEEN READ. BFLEARG IS NON-ZERO 
IN EACH BUFFER LIST ENTRY FOR WHICH A DSCB HAS BEEN READ 


Eee eee EEE EES EE EE EE ESE EEE SEES ESS ESSE SSS SSE EES SEES ES EE F 


MOVECHR 


CHRLOOP 


EXIT 


OTHERERR 
* 


* 
* 


ERROR4 





EQU * 

LA  RCURRENT, LISTPRMS 
USING LISTPRMS, RCURRENT 
LA  RBLE,BFLE 

USING BFLE,RBLE 

EQU * 

L RWORK , LISTCHR 


IS DATA SET NAME GREATER THAN DSN2 
FIRST ENTRY IN PARM LIST 


FIRST BUFFER LIST ENTRY 


MOVE CCHHR ARGUMENT TO’ CALLER AREA 
ADDRESS OF CCHHR OF CALLER 


XC O(L'BFLEARG,RWORK) ,O(RWORK) ZERO CALLER CCHHR AREA 


NC BFLEARG , BFLEARG 
BZ EXIT 

MVC 
TM LISTLAST,LASTBIT 
BO EXIT 

LA RCURRENT, LISTNEXT 
LA RBLE, BFLELN (, RBLE) 


B CHRLOOP 
EQU * 
L 13, SAVEAREA+4 


RETURN (14,12) 
LM 143.12,12(13) 


BR 14 

EQU #* 

B EXIT 
DC F'4!' 


ICVAFBFL DSECT=NO 


IS CCHHR ZERO 
BRANCH IF YES-NO MORE DSCBS 


O(L'BFLEARG, RWORK) ,BFLEARG MOVE CCHHR TO CALLER AREA 


LAST ENTRY IN PARM LIST? 
BRANCH IF YES 

NEXT ENTRY IN LIST 

NEXT BUFFER LIST ENTRY 
TEST NEXT BFLE 

RETURN TO CALLER 


RESTORE THE REGISTERS 
RETURN 


ERROR PROCESSING 


RETURN 

RETURN CODE 4 

BUFFER LIST WITH ONE BUFFER LIST * 
ENTRY 
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FKEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK EK 


Set tee ee eee ee ee ee REE EE ES EE EES SEE EE EEE SESE SEE ESE SESE EE EEE ES ESE EE EE EE SS 


+ BUFFER LIST HEADER 
+BFLHDR DS OF 
+BFLHNOE DS Ki 
+BFLHFL DS XL1 
+ ORG  BFLHFL 
+BFLHKEY DS XL1 
+BFLHVIR EQU  xX'08' 
+BFLHDSCB EQU  X'04' 

+ DS XL1 
+BFLHSP DS XL1 
+BFLHFCHN DS A 

+% 

+BFLHLN EQU  *-BFLHDR 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 


PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
FORWARD CHAIN PTR TO NEXT BUF. 
LIST 

LENGTH OF BUFFER LIST HEADER 


FEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK KK KK KK KK 


Tet eee eee eee eee SEE SSE SESE S SESE ESE SEE SEES ESSE SESE ESSE SESE STS ESE SES EEE EEE SF 


+ BUFFER LIST ENTRY 
+BFLE DS OF 
+BFLEFL DS Ki 
+BFLERBA EQU  xX'80' 
+BFLECHR EQU  xX'40! 
+BFLETTR EQU  X'20' 
+BFLEAUPD EQU  xX'10' 
+BFLEMOD EQU  x'08! 
+BFLESKIP EQU  xX'04' 
+BFLEIOER EQU  X'02' 

+ DS XL1 
+BFLELTH DS 4 iy 

+H 

+BFLEARG DS XL5 

+ ORG  BFLEARG+1 
+BFLEATTR DS XL3 

+ ORG BFLEARG+1 
+BFLEARBA DS XL4 
+BFLEBUF DS A 
+BFLELN EQU  *-BFLE 


DS CL (4*BFLELN) 
SAVEAREA DS 18F 
DSCB DSECT 

IECSDSL1 (1) 


+IECSDSL1 EQU * 


+IECSDSF1 EQU  IECSDSL1 
+DS1DSNAM DS CL44 
+DS1FMTID DS CLA 
+DSIDSSN DS CL6 
+DS1VOLSQ DS XL2 
+DS1CREDT DS XL3 
+DS1EXPDT DS XL3 
+DS1NOEPV DS XL1 
+DS1NOBDB DS XL1 
+ 

+ DS XL1 
+DS1SYSCD DS CL13 
+ DS x7 
+DS1DSORG DS XL2 
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BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 
ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 
DATA IN BUF. HAS BEEN MODIFIED 
SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB (CCHHR) 


'TTR' OF ARGUMENT 


"RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FOUR BUFFER LIST ENTRIES 


SAVE AREA 


FORMAT 1 DSCB DATASET NAME AND - 
DATA 
FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 

RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 














+% 
+DS1DSGIS 
+% 
+DS1DSGPS 
+% 
+DS1DSGDA 
+DS 1DSGCX 
+% 

+% 
+DS1DSGPO 
+DS 1DSGU 
4k 

+% 

+% 

+% 
+DS1DSGGS 
+DS 1DSGTX 
+DS 1DSGTQ 
+e 
+DS1ACBM 
+DS1DSGTR 
+% 

+% 
+DS1RECFM 
+DS10PTCD 
+DS1BLKL 
+DS1LRECL 
+DS1KEYL 
+DS1RKP 
+DS1DSIND 
+DS1SCALO 
+DS1LSTAR 
+DS1TRBAL 
+ 
+DS1EXT1 
+% 

+% 

+ 

4% 
+DS1EXT2 
+DS1EXT3 
+DS1PTRDS 
+DS1END 
DSCBLTH 
LIST 
LISTSTRT 
LISTPRMS 
LISTBUF 
LISTCHR 
LISTLAST 
LASTBIT 


LISTNEXAT 
EXAMPLE5 


EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU: 
EQU 
EQU 
EQU 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
FIRST 


SECOND BYTE 
THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 


DS 
DS 

DS 
EQU 
EQU 
DSECT 
DS 
EQU 
DS 

DS 

DS 
EQU 
DS 
EQU 
CSECT 


X'80' 
X'40' 


X'20' 
X'10' 
X'08' 
X'04' 
X'02' 
X'0O1' 


xX'80' 
X'40' 
> aes Os 


X'10°) 


X'08' 
X'O4' 
X'02' 
X'O1' 
XL1 
XL1 
XL2 
XL2 
XL1 
XL2 
XL 1 
XL4 
XL3 
XL2 
XL2 
XL10 
BYTE 


* 


FIRST BYTE OF DS1DSORG 


IS - INDEXED SEQUENTIAL 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 
ORGANIZATION 

DA - DIRECT ORGANIZATION 

CX - BTAM OR QTAM LINE GROUP 
RESERVED 

RESERVED 

PO - PARTITIONED ORGANIZATION 
U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 


SECOND BYTE OF DS1DSORG 
GS - GRAPHICS ORGANIZATION 
TX - TCAM LINE GROUP 
TQ - TCAM MESSAGE QUEUE 
RESERVED ; 
ACCESS METHOD CONTROL BLOCK 
TR - TCAM 3705 
RESERVED 
RESERVED 
RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 
RELATIVE KEY POSITION 
DATA SET INDICATORS 
SECONDARY ALLOCATION 


aOTA 


aOTA 


aOTA 
aO1A 
aOTA 
aO1A 
aO1A 
aOI1A 


aOTA 
aOTA 
aOTA 
aOTA 
aO1A 
aO1A 
QaOTA 
aOTA 


LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 


RESERVED 

FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 

UPPER LIMIT 


NEXT DOUBLEWORD 


HKRHKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KK KKK K 


* 
* 
a 
* 


READ DSCBS WITH CCHHR GREATER THAN THE CCHHR IN THE FIRST 


BUFFER LIST ENTRY. 


HH HK HK KK He KK KK KK HK HK KK KKK KK KK KK KK KK HK HK HK KK KK KK KK KK KK KK KK KK KK 





Appendix B. Examples of VTOC Access Macros 











XL10 SECOND EXTENT DESCRIPTION 
XL10 THIRD EXTENT DESCRIPTION 
XL5 POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 
* 
*-TECSDSL1 LENGTH OF DSCB 
PARAMETER LIST 
F ADDRESS OF CCHHR TO START SEARCH 
* 
F BUFFER ADDRESS 
OF ADDRESS OF CCHHR FIELD 
x BYTE 
X'80' LAST DOUBLE WORD 
AL3 3 BYTE ADDRESS OF CCHHR 
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CVPL CVAFSEQ ACCESS=GT, 


BUFLIST=BFLHDR, 


MF=L 
+ CNOP 0,4 
+CVPL EQU * 
+ DC CL4'CVPL' 
+ DC AL2 (ICV6E-CVPL) 
+ DC XL1'O4' 
+ DC XL1'OO' 
+ DC B'00100000'! 
+ DC B'OOOOOO0O0' 
+ DC H'O' 
+ DC A(Q) 
+ DC A(Q) 
+ DC A (BFLHDR) 
+ DC A(0) 
+ DC A(0O) 
+ DC A(Q) 
+ DC A(0) 
+ DC A(Q) 
+ DC A(0) 
+ DC A(0) 
+ DC A(0O) 
+ DC A(Q) 
+ DC A(Q) 
+ICV6E EQU * 

ORG CVPL 

CVPLMAP ICVAFPL DSECT=NO 


ADDRE 


EXPAN 
CVPL 





SS OF BUFFER LIST * | fe 


EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 

D MAP OVER LIST 

MAP 


“pe ie ak oe oie ok ae 2 oie ok ok 2 ok eo OK kK KK KK KR KK KK KKK KK KKK KKK KEK KKK KKK KKKKKHKKKKKKKKKKEK 


+ CVAF PARAMETER LIST 


af} 2K 2 oie 2 ok 2 of 2 ok oe fe ok ke fe ok ok oe ok oe ok ok KR KK KK KKK KKK KKK KKK KKK KKK KKK KEKKKKKKKKKKKKKEK 


+CVPLMAP DS OF 
+CVLBL DS CLA 
+CVLTH DS H 
+CVFCTN DS XL1 
+CVDIRD EQU- xX'O1' 
+CVDIWR EQU- xX'02' 
+CVDIRLS EQU- xX'03'! 
+CVSEQGT EQU x'04' 
+CVSEQGTE EQU xX'05' 
+CVDMIXA EQU- x'06' 
+CVDMIXD EQU- x'07' 
+CVDMALC EQU xX'08'! 
+CVDMRLS EQU- x'09' 
+CVDMMAP EQU- X'OA' 
+CVVOL EQU  X'OB' 
+CVVRFRD EQU x'0C' 
+CVVRFWR EQU  xX'OD' 
+CVSTAT DS XL1 

+ 

+CVFL1 DS XL1 
+CV1IVT EQU  xX'80' 
+CVIIOAR EQU  xX'40' 
+CV1PGM EQU- xX'20! 
+CV1IMRCDS EQU  xX'10! 
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Cc 
E 
L 
F 
C 
& 
C 
Cc 
C 
Cc 
C 
C 
C 
Cc 
Cc 
Cc 
Cc 
S 
B 
F 
I 
I 


VAF PARAMETER LIST 
BCDIC 'CVPL' 

ENGTH OF CVPL 
UNCTION BYTE 

VAFDIR ACCESS=READ 
VAFDIR ACCESS=WRITE 
VAFDIR ACCESS=RLSE 
VAFSEQ ACCESS=GT 
VAFSEQ ACCESS=GTEQ 
VAFDSM ACCESS=IXADD 
VAFDSM ACCESS=IXDLT 
VAFDSM ACCESS=ALLOC 
VAFDSM ACCESS=RLSE 
VAFDSM ACCESS=MAPDATA 
VAFVOL ACCESS=VIBBLD 
VAFVRF ACCESS=READ 
VAFVRF ACCESS=WRITE 
TATUS INFORMATION (SEE LIST * 
ELOW) 

IRST FLAG BYTE 
NDEXED VTOC ACCESSED 
OAREA=KEEP 


BRANCH= (YES, PGM) 
MAPRCDS=YES 

















+CV1IRCDS 
+CV 1MAPIX 
+CV 1MAPVT 
+CV IMAPVL 
+CVFL2 
+CV2HIVIE 
+CV2VRF 
+CV2CNT 
+CV2RCVR 
+CV2SRCH 
+CV2DSNLY 
+CV2VER 
+CV2NLEVL 
+%* 

+ 

+CVUCB 
+CVDSN 
+CVBUFL 
+CVIRCDS 
+CVMRCDS 
+CVIOAR 
+CVDEB 
+CVARG 
+CVSPACE 
+CVEXTS 
+CVBUFL2 
+CVVRFDA 
+CVCTAR 
+CVPLNGTH 


+% 


EQU 
EQU 
EQU 
EQU 
DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
EQU 


X'08' 
X'O4' 
X'O2' 
X'O1' 


¥DP PPP rr rrr rrr 


VALUES OF CVSTAT 


-CVPLMAP 


IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 
CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 


END 
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Example 6: Using the CVAFTST and CVAFDSM Macros 


This example returns a format-5 DSCB to the caller. The format-5 DSCB is 
constructed by this program if the volume contains an indexed VTOC. The 

_ format-5 DSCB is read by another program, FSRTN (not described in the 
example), if the volume contains a nonindexed VTOC. 


The CVAFTST macro is used to determine if a nonindexed VTOC is on the 
volume. a 


If the CVAFTST return code is neither 0 nor 4 (a nonindexed VTOC is on the 
volume), the CVAFDSM macro is issued to obtain up to 27 extents from the 
VPSM in the VTOC index. The program does not determine whether the 
CVAFTST return code is 8 (volume contains indexed VTOC) or 12 (it cannot 
be determined what type of VTOC is on the volume). In either case, the 
CVAFDSM macro is issued. If the CVAFTST return code is 12, the __ 
CVAFDSM macro call will cause CVAF to determine whether an indexed or a 
nonindexed VTOC is on the volume, and the CV1IVT bit will be set to one or 
zero, accordingly. 


The extent table (at label EXTABL) is initialized to request 27 extents from the 
CVAFDSM macro, which is one more than the number of extents that fit in a 
format-5 DSCB. The format-5 DSCB is constructed from the first 26 extents 
returned from the CVAFDSM call. 


The first extent in the extent table is initialized from the last extent in the 
format-5 DSCB area supplied by the caller of the program. If this is the first 
call, the program assumes that the format-5 area is initialized to zero. Thus, the 
first extent in the extent table has a value of zero to serve as the starting place 
for the extent search. If this is the second or subsequent call, the last extent in 
the format-5 area would be the last extent obtained from the previous 
CVAFDSM call. 


The format-5 chain pointer field (DSSPTRDS) is set to a nonzero value if 
CVAFDSM returned a 27th extent. In this case, the program will be calied 


again to obtain another format-5 DSCB. 


The program’s return code is 0 if no errors were encountered and 4 if an error 
was encountered. — 


This program must be APF authorized. 


EXAMPLE6 CSECT 
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STM 14,12,12(13) 


BALR 12,0 
USING *,12 
ST 13, SAVEAREA+4 


LA RWORK, SAVEAREA 
ST RWORK,8(, 13) 
LR 13 ,RWORK 
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PEER EEE EEE ESE SEE EEE ESE EEE EEE SESE EEE SE SEE ESS EERE SESE ES SES EE SE 


* 


* REGISTERS 
* 


Eee EEE EEE EEE ESE SELES EEE ESSERE SE EE RSE EERE SSE SESE ESE EES ESE EE SE 


DEB ADDRESS SUPPLIED BY CALLER 
UCB ADDRESS SUPPLIED BY CALLER 


RDEB EQU 3 
RUCB EQU 4 
RF5 EQU 5 
RWORK EQU 6 
REG15 EQU 15 
* 

KF5 EQU 26 


* 


ADDRESS OF 
BY CALLER 


FORMAT 5 BUFFER SUPPLIED * 


WORK REGISTER 
RETURN CODE REGISTER 15 


NUMBER OF FORMAT 5 EXTENTS 
PEER EE SEL EEE EEE EES EEE EEE ETE SES ESTES SEES SETS E ES TESST ST TS TSS 


READ FORMAT 5 DSCB OR BUILD A FORMAT 5 DSCB IF 


AN INDEXED VTOC 


UCB ADDRESS SUPPLIED IN RUCB. 
RF5 CONTAINS THE ADDRESS OF THE FORMAT 5 DSCB BUFFER. IT 
CONTAINS THE LAST FORMAT 5 DSCB READ OR BUILT. THE FORMAT 5 


IF THE FORMAT 5 DSCB BUFFER RETURNED TO THE CALLER HAS A 


NONZERO VALUE IN DSSPTRDS, 


THIS ROUTINE WILL BE CALLED 


AGAIN TO OBTAIN THE NEXT FORMAT 5 DSCB. 


* 
* 
F 3 
* 
x 
* BUFFER IS ZERO IF THIS IS THE FIRST CALL 
* 
* 
* 
x 
* 


(Eee EEE EEE EEE EEE EERE EEE SEES SEES EEE ESSE SSE SESS ESE LES ES ESE EE EE 


USING IECSDSF5,RF5 
CVAFTST UCB=(RUCB) 


+ CNOP 0,4 

+ LR 1,RUCB 

+ L 15:16 

+ L 15,328(,15) 
+ L i412 3) 
+ LTR 15%15 

+ BZ ICV1E 

+ L 15340; 15) 

+ BALR 14,15 
+ICVIE EQU * 


LTR REG15,REG15 
BZ UNINDXD 

Cc REG15,NOTIXRC 
BE UNINDXD 


ADDRESSABILITY TO FORMAT 5 BUFFER 


TEST. VICE 


START OF CVAFTST MACRO 


LOAD 
LOAD 
LOAD 
TEST 
CVAF 
LOAD 


LOAD PARAMETER REG 1 
THE CVT 
VS1/VS2 COMMON EXTENSION2 
THE CVAF TABLE ADDRESS 
FOR ZERO VALUE 
IS NOT ON THE SYSTEM 
POINTER TO CVAF TEST E.P. 


BRANCH AND LINK TO CVAF TEST 
END OF CVAFTST 


READ NEXT 
UNINDEXED 
READ NEXT 


FORMAT 5 
VTOC? 
FORMAT 5 


(EEE EE EEE SEE EEE EEE EEE EEE EES ERE SSE ESE SESS SESS SES EEE SE EES ES ES 


* 


* ASSUME INDEXED VTOC UNLESS CVAFDSM CALL INDICATES UNINDEXED 


* 


(EEE EEE EEE EEE EEE EES SEES EEE SESE SESE SESE ESE SEE ESSERE EE SESE SS ES SS SF 


MVC EXTS(L'DSSAVEXT) , DSSMAVET+L'DSSMAVET-L'DSSAVEXT MOVE THE * 
LAST EXTENT FROM FORMAT 5 TO FIRST * 
ENTRY IN THE EXTENT TABLE 


CVAFDSM MF=(E,CVPL), 


UCB=(RUCB) , 
DEB=(RDEB) , 
BRANCH=YES 








GET 27 EXTENTS FROM CVPL 

RUCB ADDRESS REQUIRED 

RDEB ADDRESS REQUIRED BY 
UNAUTHORIZED PROGRAMS CALLING CVAF 

BRANCH ENTRY CALL 


* *& & & 
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++++4+4 


LTR 


BNE 
CLI 
BNE 


NOERROR EQU 


MVC 
MVC 


MVI 
MVC 


XR 


aC 
NC 


BZ 
MVI 


B 


UNINDXD EQU 


t++++4++ 


LINK 


CNOP 
BAL 
DC 
DC 
DC 
SVC 


RETURN  EQU 


+ 


+ 


+ 


L 





1,CVPL LOAD PARAMETER REG 1 


15,16 : LOAD THE CVT 
15,328(,15) LOAD VS1/VS2 COMMON EXTENSION2 
159.1244 .15) LOAD THE CVAF TABLE ADDRESS 
15,0(,15). : LOAD THE CVAF ADDRESS 
14,15 BRANCH AND LINK TO CVAF 
CVFL1,CV1IVT IS THIS INDEXED VTOC 
UNINDXD READ FORMAT 5 IF NOT 
REG15,REG15 ANY ERROR 
NOERROR 
REG15,RCO4 
OTHERERR UNEXPECTED ERROR 
CVSTAT, STATO32 END OF DATA 
OTHERERR UNEXPECTED ERROR 
* BUILD FORMAT 5 
DSSKEYID,F5ID 
DS5SAVEXT (L'DSSAVEXT+L'DS5SEXTAV) , EXTS MOVE IN EXTENTS * 


TO DS5SFMTID 
DS5FMTID,C'5' 


DS5MAVET,EXTS+L'DSSAVEXT+L'DSSEXTAV MOVE REMAINING * 
EXTENTS 

REG15,REG15 RETURN CODE ZERO 

DSSPTRDS , DS5PTRDS ZERO CHAIN POINTER 

EXTS+L'EXTS-L' DSSAVEXT (L'DS5SAVEXT) , EXTS+L' EXTS-L'DS5SAVEXT* 
IS LAST(27TH) EXTENT FROM CVAF * 
ZERO? 

RETURN BRANCH IF YES-LEAVE DS5PTRDS ZERO 


DS5PTRDS+L'DS5PTRDS-1,1 SET DSSPTRDS NONZERO TO SIMULATE * 
THERE BEING ANOTHER FORMAT 5 


RETURN 
x CALL ROUTINE TO READ NEXT FORMAT 5 
EP=F5RTN LINK TO FORMAT 5 ROUTINE. RETURN * 
CODE PASSED BACK IN REG15 
0,4 
15,*+20 | LOAD SUP.PARAMLIST ADR 
A(*+8) ADDR OF EP PARAMETER 
A(0) DCB ADDRESS PARAMETER LCOA 
CL8'F5RTN' EP PARAMETER 
6 ISSUE LINK SVC 
RETURN TO CALLER 


13, SAVEAREA+4 


RETURN (14,12) ,RC=(15) 


L 
LM 
BR 


OTHERERR EQU 


DSCB 


L 
B 
DSECT 
ITECSD 


+IECSDSL5 EQU 
+IECSDSF5 EQU 
+DS5KEYID DS 
+DSSAVEXT DS 


+% 
+% 
+% 
+% 


BYTES 


BYTES 
BYTE 


14,12(13,0) RESTORE REGISTER 14 
0,12,20(13) RESTORE THE REGISTERS 
14 RETURN 

* _ ERROR 

REG15,RCO4 ERROR RETURN CODE 

RETURN 
SL1 (5) | 

* FORMAT 5 DSCB 

ITECSDSL5 | 

XL4 KEY IDENTIFIER 

XL5 AVAILABLE EXTENT 

i -e2 RELATIVE TRACK ADDRESS OF THE FIRST TRACK 

IN THE EXTENT 
3-4 NUMBER OF UNUSED CYLINDERS IN THE EXTENT 
5 NUMBER OF ADDITIONAL UNUSED TRACKS 
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oe +DSSEXTAV DS XL35 SEVEN AVAILABLE EXTENTS 





+DS5SFMTID DS CL1 FORMAT IDENTIFIER 
+DSSMAVET DS XL90 EIGHTEEN AVAILABLE EXTENTS 
+DSSPTRDS DS XL5 | POINTER TO NEXT FORMAT 5 DSCB 


+DSSEND EQU- * 
EXAMPLE6 CSECT 


NOTIXRC DC F'q' CVAFTST RETURN CODE-UNINDEXED 
RCO4 DC F'q' RETURN CODE 4 
F5ID DC XL4'0505050505' FORMAT 5 FIELD, DSSKEYID 
SAVEAREA DS 18F REGISTER SAVE AREA 
EXTABL DS OCL(1+(KF5+1) *L'DSSAVEXT) EXTENT TABLE 
EXTNO DC AL1 (KF5+1) NUMBER OF EXTENTS IN TABLE 
EXTS DS CL( (KF5+1) *L'DSSAVEXT) EXTENTS 
CVPL CVAFDSM ACCESS=MAPDATA, * 
COUNT=NO, DO NOT COUNT EXTENTS x 
MAP=VOLUME, ACCESS VOLUME SPACE MAP * 
EXTENTS=EXTABL, EXTENT TABLE ADDRESS * 
MF=L LIST FORM OF MACRO 
+ CNOP 0,4 
+CVPL EQU * 
+ DC CL4'CVPL' EBCDIC 'CVPL' 
+ DC AL2 (ICV9E-CVPL) LENGTH OF CVPL 
+ DC XL1'OA' FUNCTION CODE 
+ DC XL1'00! STATUS INFORMATION 
+ DC B'00100001' FIRST FLAG BYTE 
+ DC B'00000000' SECOND FLAG BYTE 
+ DC H'O! RESERVED 
+ DC A(0) UCB ADDRESS 
+ DC A(0) DATA SET NAME ADDRESS 
+ DC A(0) BUFFER LIST ADDRESS 
+ DC A(0) INDEX VIR'S BUFFER LIST ADDRESS 
e3 + DC A(0) MAP VIR'S BUFFER LIST ADDRESS 
{ + DC A(0) I/O AREA ADDRESS 
2 + DC A(0) DEB ADDRESS 
+ DC A(0) ARGUMENT ADDRESS 
+ DC A(0) SPACE PARAMETER LIST ADDRESS 
+ DC A(EXTABL) EXTENTS TABLE ADDRESS 
+ DC A(0) NEW VRF VIXM BUFFER LIST ADDR 
+ DC A(0) VRF DATA ADDRESS 
+ DC A(0) COUNT AREA ADDRESS 
+ICV9E EQU * END OF CVPL 
ORG CVPL OVERLAY CVPL WITH EXPANSION OF MAP 


CVPLMAP ICVAFPL DSECT=NO 
he Ee EE a ie ea i a a oe a a oe a a ae oe a oe ae ae oe de oe oe ao eo oe oR 


+* CVAF PARAMETER LIST 

TS SESE ESE SESE ESE SEE EEE SE SESE SES ESSE SESE SESE SESE SEES ELE EEE SESE ES SEE EE EE EEE OS SE 
+CVPLMAP DS OF CVAF PARAMETER LIST 
+CVLBL DS CL4 EBCDIC 'CVPL' 

+CVLTH DS H LENGTH OF CVPL 
+CVFCIN DS XL1 FUNCTION BYTE 
+CVDIRD EQU- X'01' CVAFDIR ACCESS=READ 
+CVDIWR EQU- X'02' CVAFDIR ACCESS=WRITE 
+CVDIRLS EQU  X'03' CVAFDIR ACCESS=RLSE 
+CVSEQGT EQU  xX'04' CVAFSEQ ACCESS=GT 
+CVSEQGTE EQU X'05' CVAFSEQ ACCESS=GTEQ 
+CVDMIXA EQU  xX'06' CVAFDSM ACCESS=IXADD 
+CVDMIXD EQU  xX'07' CVAFDSM ACCESS=IXDLT 
+CVDMALC EQU  X'08' CVAFDSM ACCESS=ALLOC 
+CVDMRLS EQU  xX'09' CVAFDSM ACCESS=RLSE 


+CVDMMAP EQU X'OA' CVAFDSM ACCESS=MAPDATA 


Appendix B. Examples of VTOC Access Macros 295 








Sag OO BRS ee Se bo crete oe ree eS rane 2 Tiras Aa SRT Ey TE Daal aT” TR SPT RP 7G RS POR RAPE ALIS SAAS BTEC CR a CR 7 a a a aT 


+CVVOL EQU  xX!'OB' 
+CVVRFRD EQU- x'OC' 
+CVVRFWR EQU  xX'OD' 


+CVSTAT DS XL1 
+ 
+CVFL1 DS XL1 


+CV1IVT EQU- x'80'! 


+CV1IOAR EQU  xX'40' 
+CV1PGM EQU- xX'20' 
+CV1IMRCDS EQU xX'10! 
+CV1IRCDS EQU <X'08' 
+CV1IMAPIX EQU xX'04' 
+CV1IMAPVT EQU  xX'02' 
+CV1IMAPVL EQU xX'01' 
+CVFL2 DS XL1 

+CV2HIVIE EQU x'80' 
+CV2VRF EQU- x'4O' 
+CV2CNT EQU xX'20' 
+CV2RCVR EQU  xX'10' 
+CV2SRCH EQU  xX'08' 
+CV2DSNLY EQU xX'04' 
+CV2VER  EQU- xX'02' 
+CV2NLEVL EQU xX'01' 


+% 

+ DS H 

+CVUCB DS A 

+CVDSN DS A 

+CVBUFL DS A 
+CVIRCDS DS A 
+CVMRCDS DS A 
+CVIOAR DS A 

+CVDEB DS A 

+CVARG DS A 
+CVSPACE DS A 

+CVEXTS DS A 
+CVBUFL2 DS A 
+CVVRFDA DS A 
+CVCTAR DS A 
+CVPLNGTH EQU *—CVPLMAP 
+%* VALUES OF CVSTAT 





CVAFVOL ACCESS=VIBBLD Pa 
CVAFVRF ACCESS=READ ( 
CVAFVRF ACCESS=WRITE Wu 
STATUS INFORMATION (SEE LIST X 

BELOW) 


FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 
ITOAREA=KEEP 

BRANCH= (YES, PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 
CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 


DEB ADDRESS van 
ARGUMENT ADDRESS 7 
SPACE PARAMETER LIST ADDRESS Se 


EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


+* (THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 


END 
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Appendix C. VTOC Index Error Message and Associated Codes 


Error Message 


Explanation 


System Action 


When CVAF finds an error in a VTOC index, it issues this message: 


IEC606I VTOC INDEX DISABLED ON devy,volser, 


code,|rba[,secno,offset]] 





In addition, CVAF puts a return code in the CVSTAT field of the CVPL. 


The Common VTOC Access Facility (CVAF) detected a VTOC index error on 
the device “dev” with volume serial number “‘volser.”’ ‘‘code”’ is a number that 
represents the kind of VTOC index error encountered. ‘“‘rba” is the RBA of the 
VIR in the VTOC index that contains a structure error indicated by “‘code.”’ If 
the VIR is a VIER, the section number in the VIER containing the VTOC index 
entry is supplied in ‘‘secno,”’ and the offset into the section of that VTOC index 
entry is supplied in “offset.” 


The VTOC index is disabled by zeroing the index bit in the format-4 DSCB and 
setting the bit in the first high-level VIER that indicates invalid VTOC index 
structure. The VTOC will be converted to nonindexed format when DADSM 
next allocates space on the volume. A system dump is written to the 
SYS1.DUMP data set, and an entry is made in the SYS1.LOGREC data set. 
The message IEC604I (which indicates that the VTOC convert routines have 
been used) will be issued later. 
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Programmer Response 


Examine the system dump and a print of the VTOC index, and use the 
information in message IEC606I to determine the cause of the VTOC index 
structure error. 


Routing and Descriptor Codes 


The routing codes are 4 (direct access pool) and 10 (system/error maintenance), 
and the descriptor code is 4 (system status). 


Codes Put in the CVSTAT Field 


Code 

0(X'00') 
1(X'01") 
2(X'02") 
4(X'04") 
5(X'05') 
6(X'06") 
7(X'07") 
8(X'08") 


9(X'09') 


10(X'0A") 
11(X'0B') 


12(X'0C') 


Meaning 

No error. 

Data set name not found, or VIER is empty. 

Argument is outside VTOC extents or RBA range of VTOC index. 
Invalid parameter supplied (wrong key), or VRFAREA too small. 
DSN keyword omitted. 

Not authorized to perform this furiction. 

Buffer list omitted. 

DEB invalid or omitted or not open to VTOC. 


IOAREA=KEE?P and user not authorized, or I/O area supplied and either user not authorized or 
CVAFVOL function. 


Y : ‘OC 
e 





Function not supported on OS 


DSCB is not format-O DSCB attd VERIFY= YES. 





MAPRCDS= YES and/or IXRGDS+KEEP but VTOC is nonindexed. 
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Code 

13(X'0D") 
14(X'0E') 
15(X'0F') 


17(X'11') 


19(X'13') 
22(X'16') 
23(X'17') 
24(X'18"') 


25(X'19"') 


27(X'1B') 
28(X'1C') 


29(X'1D') 


30(X'1E') 


31(X'1F') 


32(X'20') 





Meaning 

IXRCDS=KEEP not specified for CVAFDSM ACCESS=IXADD or [IXDLT. 
CTAREA keyword omitted. 

UCB invalid, volume not mounted; VIO unit, not DASD. 

DSCB length invalid for the function requested: 96 bytes for CVAFDIR 
ACCESS=WRITE,VERIFY= YES; 140 bytes for CVAFSEQ reading in data set name 
sequence; 96 bytes for CVAFSEQ reading in physical sequence. 

UCB omitted and CVAF I/O area not supplied. 

Data set name already supplied in index. 

Invalid DSN supplied (44 X'FF' is a reserved data set name). 


ARG keyword not supplied. 


Conflicting or incomplete information specified in the space table fora CVAFDSM 
ACCESS=ALLOC, MAP=VOLUME request. 


VTOC index full. No free VIRs available and a VIER split is required. 
Space keyword omitted (CVSPACE field zero in CVPL). 


CVAFDSM ACCESS=ALLOC: No format 0 DSCB available (MAP=VTOC), or VTOC index 
full (MAP=INDEX), or volume space not available (MAP=VOLUME). 


CVAFDSM ACCESS=ALLOC: CCHHR (MAP=VTOC) or RBA MAP=INDEX or volume 
space extent (MAP=VOLUME) already allocated. 


CVAFDSM ACCESS=ALLOC or ACCESS=MAPDATA: CCHHR supplied outside VTOC 
extents (MAP=VTOC), or RBA outside VTOC index extents (MAP=INDEX), or volume space 
extent invalid or outside volume (MAP=VOLUME). 


End of data. CVAFDSM ACCESS=MAPDATA: no more free extents in VPSM. CVAFSEQ: 
no more names in index or DSCBs in VTOC. For indexed access, no DSN in VTOC index with 
higher or higher-or-equal key than that supplied. For physical-sequential access, no DSCB in the 
VTOC has a higher argument than that supplied. For a multiple DSCB request, the last DSCB in 
the VTOC was read and more DSCBs were requested. 
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Code 
33(X'21') 


34(X'22') 


42(X'2A') 
43(X'2B') 
44(X'2C') 


45(X'2D') 


46(X'2E') 


47(X'2F') 
48(X'30') 
49(X'31") 
50(X'32') 
52(X'34') 
53(X'35') 
54(X'36') 
55(X'37') 
56(X'38') 


57(X'39") 


58(X'3A') 


Meaning 

EXTENTS keyword omitted, or supplied number of extents is zero. 

CVAFDSM ACCESS=RLSE and format-0 DSCB already free (MAP=VTOC), or VIER 
already unallocated (MAP=INDEX) or volume space extent already unallocated 
(MAP=VOLUME). 

VRF data supplied for write too long. 

Buffer list is for VIRs, but a DSCB buffer list is required. 


No buffer list entry found. 


Invalid DSCB buffer length (neither 96 nor 140) in buffer list entry, or VIR buffer length not 
equal to VIB VIR size. 


Neither TTR nor CCHHR bits set in buffer list entry to be used in writing or reading a 140-byte 
DSCB. 


More than one of the TTR, CCHHR, and RBA bits set in the buffer list entry. 
Both the DSCB and VIR bits set in the buffer list header. 
RBA bit set in a buffer list entry for a DSCB buffer list. 


TTR or CCHHR bit set in buffer list entry but buffer list header indicates buffer list is for a VIR. 


Combination of MAP and COUNT not supported. a, 


MAP omitted. 

Buffer list for a VIR chained to or from a buffer list for a DSCB. 
Unauthorized caller and VIB not initialized. 

MAPRCDS= YES not specified but required. 


Buffer list for a DSCB supplied, but buffer list for a VIR is required (in MAPRCDS or IXRCDS 
buffer list address in CVAF parameter list). 


Neither the VIR nor DSCB bit set in a buffer list header. 
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Code 

60(X'3C') 
61(X'3D') 
62(X'3E') 


63(X'3F') 


64(X'40') 


65(X'41"') 


66(X'42') 


67(X'43') 
68(X'44') 
69(X'45') 
70(X'46') 
71(X'47") 
72(X'48') 


73(X'49"') 


7T4(X'4A') 


Meaning 

Invalid or conflicting setting of allocate option byte in space parameter 

Filter criteria list address omitted (CVFCL=0) or ID not “FCL ” (CVAFFILT). 
FCLCOUNT field is zero or no elements to process (CVAFFILT). 


FCLCOUNT field is greater than 1 and FCL1LIST indicates a generic data set name 
(CVAFFILT). 


Insufficient number of user buffer list entries to complete this request. All data set names in the 
filter criteria list up to this point processed successfully. Use RESUME function to continue 
processing (CVAFFILT). 

Buffer list entry error, for example, buffer length not 140 bytes (CVAFFILT). 


ACCESS=RESUME and filter save address (FSA) omitted (CVFSA=0), or FSA not in CVAF 
protect key (CVAFFILT). 


Invalid partially qualified data set name for generic access (CVAFFILT). 

Filter criteria list not in user key (CVAFFILT). 

Internal GETMAIN error (CVAFFILT). 

Direct VTOC access I/O error (CVAFFILT). 

Sequential VTOC access I/O error (CVAFFILT). 

Error in CVAFFILT processing. RESUME function not recommended (CVAFFILT). 
Insufficient number of user buffer list entries to complete this request. Error in DSCB chain. One 
or more names in the filter criteria list not processed successfully; however, RESUME function 


recommended for remaining DSCBs (CVAFFILT). 


Data set name information is invalid (FCLDSNLG is either “‘O”’ or greater than '44', or 
FCLDSNA is either “‘0”’ or not in user key) (CVAFFILT). 


127(X'7F') I/O error occurred. 


128(X'80') Reserved. 
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Code Meaning 


129(X'81') The first high-level VIER as indicated in the VIXM does not have the flag bit set indicating it is \ 
the first high-level VIER. 


130(X'82') A horizontal or vertical VIER pointer is outside the RBA range of the VTOC index. 
131(X'83') A vertical VIER pointer points to a VIR that is not a VIER (invalid ID in header). 

132(X'84') A level n vertical index entry pointer points to a VIER that is not at level n - 1. 

133(X'85') Level n horizontal index entry pointer points to VIER that is not at level n. 

134(X'86') Horizontal VIER/map pointer points to a VIR that is not a VIER/map (invalid ID in header) ‘ | 


135(X'87') Horizontal map pointer points to VIR that is not one of the first n VTOC index records (n is 
recorded in VIXM field VIMRCDS), or the first record in the VTOC index is not a VIXM. — 


136(X'88') A level-1 index entry contains a CCHHR pointer that is outside the VTOC extent. 


137(X'89') The first high-level VIER, as indicated in the VIB, does not have the flag bit set indicating it is 
the first high-level VIER. (This error is either recovered from by updating the VIB from the | 
VIXM, or the error is changed to 129.) 


138(X'8A') The RBA of the VTOC index VIR does not match the RBA recorded in the header of the 
record. 


139(X'8B') The first record of a map (VIXM, VPSM, or VMDS) is not one of the first n WTOC index 
records (n is recorded in the VIXM field, VIMRCDS). aed 


140(X'8C') The data set name in a level n + 1 VIER entry is lower than the high key of the level n VIER 
that the level n + 1 VIER entry points to. 


141(X'8D') First high-level VIER structure error bit is on. 
142(X'8E') I/O error indicating the VTOC index is not formatted correctly. 


143(X'8F') Either the index bit is zero, or the DOS bit is zero in the format-4 DSCB of a VTOC previously 
found to be an indexed VTOC. 


144(X'90') No SYS1.VTOCIX.nnn data set name in a VTOC whose format-4 DSCB has the index bit on, 
indicating the VTOC has an index. 
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Code 


145(X'91") 


146(X'92') 
147(X'93") 
148(X'94"') 
149(X'95') 
150(X'96') 
151(X'97') 


152(X'98') 
153(X'99') 


154(X'9A') 


155(X'9B') 
156(X'9C') 


157(X'9D') 
158(X'9E') 


159(X'9F') 





Meaning 


The data set name in a level n + 1 VIER entry is higher than the high key of the level n VIER 
that the level n + 1 VIER entry points to 


Four or more high-level VIERs were encountered. 

Too many levels in the VTOC index. The length of the search list was exceeded. 
VIER invalid, because offset to last section is invalid. 

VIER invalid, because offset to last entry in a section is invalid. 

Media Manager initialization failed. 

Level-2 or higher VIER contains fewer than as entries. 


RECOVER=YES specified, but the static text module (ICVIXSTO) indicates recovery is not | 
permitted. : 


The format-4 DSCB on an indexed VTOC is written with either the index- or DOS-bit zeroed on 
an indexed VTOC. 


A space map extends over more than 10 VTOC index records. 


Data set name not found in section with key greater than or equal to the name being searched 
for. The VIER section containing the name is invalid. 


Invalid VIER horizontal pointer. Horizontal pointer of VIER1 points to VIER2 whose high key 
is lower than or equal to the high key of VIER1. 


Could not find entry in level-2 or higher VIER that matches the high key of the VIER. 
Invalid section length or invalid number of sections in a VIER header. 


The first high-level VIER pointed to by the VIB has an invalid ID in the header. 
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Appendix D. Example of an OPEN Installation Exit Module 


The description and example of IFGOEXOB (an installation-written OPEN exit 
module that takes control during OPEN for a DCB) has been moved to Data 
Facility Product: Customization. 
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Appendix E. DFP ISMF Services 


Introduction 


This appendix describes services of the ISMF component of DFP available for 
use by external application programs that are executing as ISMF line operators 
or commands. See Data Facility Product: Customization for details related to 
creating new line operators or commands. This appendix is organized into the 
following sections: 


e DFP ISMF service descriptions 
e DFP ISMF messages available to external applications 
e DFP ISMF control blocks available to external applications 


Standard Linkage and Error Handling 


Input Register Usage 


ISMEF uses registers as described below. Services are accessed by creating 
required parameter lists, loading the entry point address of the desired routine 
into register 15, then branching to the address in register 15. The first four 
letters of all entry point names identify associated control blocks. 


The following table describes registers on input to a line operator or command 
running in a DFP ISMF environment. 


Register Value on Input to Line Operator or Command 


0 Unused 

1 LPPL on input to line operator; CPPL on input to command 
2-9 Unused 

10 Points to GDRB 

11,12 Unused 

13 Points to standard save area of calling routine 

14 Address of return point in calling routine 
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Register Value on Input to Line Operator or Command 





15 Address of called routine 


The following table describes registers on input to a DFP ISMF service from a 
line operator or command. 


Register Value on Input to DFP ISMF Service 


0 Unused unless otherwise specified below 

1 Points to input parameter list 

2-9 Unused unless otherwise specified below 

10 Points to GDRB 

11,12 Unused unless otherwise specified below 

13 Points to standard save area of calling routine 

14 Address of return point in calling routine 

15 Address of called routine 

Output Register Usage 

The following table describes registers on output from a DFP ISMF service to a : ~ 
line operator or command, or on output from a line operator or command to Miao 
ISMF. 


Register Value on Output from DFP ISMF Service, Line Operator, 
or Command 


0-14 Unused unless otherwise specified below 


15 Return code 


Building Parameter Lists and Finding Control Blocks 
Parameter lists must be constructed in one of two ways: 


e The list consists of 31-bit pointers to required inputs, with the last entry of 
the list marked by having the high-order bit set to 1. 


¢« The list consists of a set of flag bits followed by 31-bit pointers. The flag 
bits indicate which parameters are present and which are omitted. 


Most control blocks are pointed to by fields in other control blocks. To find a 
control block, use the entry point name provided and find the control block 
whose name is equal to the first four letters of the given entry point name. The 
rest of the given entry point name identifies the field in the control block 
(identified by the first four letters) that contains the entry point. 
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Error Logging 





For example, the control block ARVT identifies the field GDRBARVT as its 
entry point. Following the rules stated above, GDRB is the control block that 
contains the entry point address for the ARVT in the field labeled GDRBARVT 
(offset 8). The GDRB lists register 10 as its entry point; therefore, you find the 
entry point for the ARVT in the field at location GDRB + 8. Some fields in 
parameter lists refer to fields in control blocks; you may locate these fields in a 
similar manner. 


If an error occurs, all services write information to the ERNT (see service 
descriptions for details). Typical error logging includes the failing module name, 
return code, reason code, and other diagnostic information. DFP ISMF creates a 
chain of ERNT control blocks to log errors. The ERTBCURR field in the 
ERTB always points to the current ERNT. 
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DFP ISMF Services - 


DGTCDT0O1 Decrement Use Count 


Function: DGTCDTO01 decrements the use count of modules loaded by 
DGTCLDO1. 


Entry Point Address: SRVTDTO1 
Input: R1 points to the parameter list described below. 


Pararneter list 


Offset 
Hex Parameter 


0 31-bit pointer to an 8-byte character variable set to the name of the 
module to be deleted 


Output: DGTCDTO01 provides a return code, as follows. 


Register states: R15 contains a return code, and the ERNT is updated as 
described below. 


Return Code ERNT Field 
Name 


ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
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DGTCDV01 Data Set Name Syntax Verification 


Function: DGTCDV01 verifies data set name syntax. If the variable pointed to 
by the last parameter in the following list is set to a blank (X'40'), unquoted 
input data set names are returned unquoted with the TSO prefix appended. 
Quoted input data set names are returned unchanged, but without quotation 
marks. 


Entry Point Address: SRVTDVO1 
Input: R1 points to the parameter list described below. 


Parameter list 


Offset 

Hex (Dec) Parameter 

0 31-bit pointer to a 60-byte character variable set to input data set 
name 

4 31-bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) full data set name 

8 31-bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) partial data set name 

C (12) 31-bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) member of partitioned data set 

10 (16) 31-bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) relative generation reference data set 

14 (20) 31-bit pointer to a 60-byte character variable to be set to output 
data set name. 

18 (24) 31-bit pointer to a 1-byte character variable set to Y (allow) or 


blank (disallow) the following: TSO prefix should not be 
appended to data set name and data set name must be unquoted 


Output: The output data set name is updated. 


Register states: R15 contains a return code, and the ERNT fields listed below 
are updated. 


Return ERNT Field 


Code Name 

0 

8 ERNTLMSG 
ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSMSG 
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Return 
Code 


12 


ERNT Field 
Name 


ERNTLMSG 
ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSERV 
ERNTSMSG 
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DGTCEP01 Free Storage and Exit 





Function: DGTCEP0!1 frees storage gotten by DGTCPRO1 and exits to the 
caller of the routine that called DGTCEPO1. 


Entry Point Address: SRVTEPO1 


Input: R1 points to the parameter list described below. 


Parameter list 
Register Parameter 
0 31-bit pointer to a 15-bit variable set to the ISMF exit return code 
1 31-bit pointer to an 8-byte character variable set to the name of 


the calling module 


2 31-bit pointer to storage to be freed 


Output: DGTCEPO01 provides a return code, as follows. 


Register states: R15 contains a return code, and the following ERNT fields are 
updated. RO contains a pointer to the return code to be passed back to the 
original caller (caller of the caller of DGTCEPO1). R1 contains a pointer to the 
size of the invoking module’s automatic data area. 


( Return ERNT Field 
: Code Name 

0 

12 
ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 
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DGTCFM01 Free Memory 


Function: DGTCFMO01 frees storage acquired through DGTCGMO1. 
Entry Point Address; SRVTFMO1 


Input: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex (Decimal) Parameter 
0 31-bit pointer to a 4-byte character variable set to the storage 
identifier of the caller 
4 31-bit pointer to a 31-bit pointer to the address of the area to be 
freed 


Output: DGTCFM01 provides a return code, as follows. 


Register states: R15 contains a return code and the following ERNT fields are 
updated. 


Return ERNT Field 


Code Name 

0 

12 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSERV 
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DGTCGM01 Get Storage 





Function: DGTCGMOl1 gets storage (which is freed by DGTCFMO01). If the 
first attempt to obtain storage fails, DGTCGMO1 deletes modules (loaded by 
DGTCLD0O1) whose use count is zero and will retry the operation. 


Entry Point Address: SRVTGMO1 


Input: R1 points to the parameter list described below. 


Parameter list 

Offset 

Hex (Decimal) Parameter 

0 31-bit pointer to a 31-bit variable set to number of storage 
bytes to be obtained 

4 31-bit pointer to a 5-byte character variable set to BLANK or 
ZERO, specifying whether to initialize obtained storage to 
zeros or blanks 

8 31-bit pointer to a 4-byte character variable set to the storage 
identifier of the obtained storage 

C (12) 31-bit pointer to a 5-byte character variable set to BELOW or 
ANY, specifying storage to be obtained from BELOW the 16 
megabyte boundary or from ANY location 

10 (16) 31-bit pointer to a 5-byte character variable set to DBLWD or 
PAGE, specifying storage to be aligned on a doubleword or 
page boundary 

14 (20) 31-bit pointer to a 31-bit variable to be set to the address of the 


obtained storage 


Output: The last field of the parameter list (address of obtained storage) is 
updated to contain a pointer to the new storage. 


Register states: R15 contains a return code and the following ERNT fields are 
updated. 


Return ERNT Field 


Code Name 

0 

12 ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSERV 
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DGTCLD01 Load a Module | Oo a 


Function: DGTCLDO1 loads a requested module into storage; if the module is . 
already loaded, DGTCLDO1 increments the module’s use count. 
Entry Point Address: SRVTLDO1 
Input: Register states: R1 points to the parameter list described below. 
Parameter list 
Offset 
Hex (Decimal) Parameter 
0 31-bit pointer to an 8-byte character variable set to the name of 
the requested module 
4 31-bit pointer to a 31-bit variable that will be updated to 
contain the entry point address of the loaded module 
Output: DGTCLD01 provides a return code, as follows, and the variable 
pointed to by the load entry point address field of the parameter list is updated. 
Register states: R15 contains a return code and the ERNT is updated as 
described below. 
Return ERNT Field = 
Code Name — 
0 
12 
ERNTMODN 
ERNTPROC 
ERNTRC 
ERNTRSNC 
SRVC 
ERNTPD 
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DGTCLG01 Place Information in the ISPF Log 


Function: DGTCLG01 creates log entries based on information from the 
current ERNT, the current IMNT, or the log buffer. If the first parameter in the 
following list is set to ERROR, the ERNT is used as the information source; if 
the first parameter is set to IMTT, the IMNT is used as the source, and if the 
first parameter is set to STATUS, the log buffer is used as the source. 


Entry Point Address: SRVTLGO1 


Input: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 
0 31-bit pointer to a 6-byte character variable set to the type of 


entry to be generated. Possible entries: ERROR, STATUS, IMTT 


4 31-bit pointer to an 8-byte character variable set to the address 
of a message to be written to the log if type was set to STATUS, 
set to blanks otherwise 


8 31-bit pointer to a 31-bit variable set to zeros 


Output: DGTCLG01 provides a return code, as follows. 


Register states: R15 contains a return code and the following ERNT fields are 
updated. 


Return ERNT Field 


Code Name 

0 

12 ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSERV 


Appendix E. DFP ISMF Services 317 








DGTCPRO01 Obtain Automatic Data Area ch 


Function: If tracing is on, DGTCPRO1 gets a module’s automatic data area, 
adds an entry to the Inter-Module Trace Table, and writes an entry to the ISMF 
log. 
Entry Point Address: SRVTPRO1 
Input: R1 points to the parameter list described below. 
Parameter list 
Register Parameter | | 
O- _ 31-bit pointer to a 31-bit variable set to the amount of storage 
needed | 
1 31-bit pointer to an 8-byte character variable set to calling module 
name 
Output: DGTEPRO1 provides a return code, as follows. 
Register states: R15 contains a return code, R1 contains the address of the new 
storage, and the following ERNT fields are updated. 
Return ERNT Field —_, 
Code Name Ne 
0 
12 ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 





318 MVS/XA System—Data Administration 








DGTCVV01 Volume Serial Number Syntax Verification 





Function: DGTCVV01 verifies volume serial number syntax. DGTCVV0O1 does 
not support quoted volume serial numbers. 


Entry Point Address; SRVTVVO1 


Input: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 
0 31-bit pointer to a 6-byte character variable set to the volume 


serial number to be checked 


4 31-bit pointer to a 1-byte character variable set to Y (allow) or | 
blank (disallow) full volume serial number | 


8 31-bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) partial volume serial number 


Output: DGTCVV01 provides a return code, as follows. 


Register states: R15 contains a return code and the following ERNT fields are 


{ = updated. 

Return ERNT Field 

Code Name 

0 

8 ERNTLMSG 
ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 
ERNTSMSG 
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DGTCWOO0O1 Word Finder | om 


Function: DGTCWO01 scans a specified section of storage for a character 
string delimited by blanks. 


Entry Point Address; SRVTWOO1 
Input: R1 points to the parameter list described below. 


Parameter list 


Offset 
Hex (Decimal) Parameter 


0 31-bit pointer to a 31-bit variable set to the start address of 
storage to be scanned 


4 31-bit pointer to a 31-bit variable set to the end address of 
storage to be scanned 


8 31-bit pointer to a 31-bit variable that will contain the address 
of the first word found 


C (12) 31-bit pointer to a 31-bit variable that will contain the size of 
the first word found 


Output: The word and size fields of the parameter list will be updated. 


Register states: R15 contains a return code and the following ERNT fields are 


updated. 

Return ERNT Field 

Code Name 

0 

12 ERNTMODN 
ERNTPROC 
ERNTRSNC 
ERNTRC 
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DGTFARF1 Find an Entry in the Data Set List Array 





Function: DGTFARF'1 finds information in the data set list array and moves the 
current row pointer to the new position. 


Entry Point Address; ARVTFIND 


Input: Register states: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 
0 31-bit pointer to a 32-bit parameter set to X'3', indicating which 
parameters are present 
4 31-bit pointer to the SELB 
8 31-bit pointer to a 3-byte character variable set to YES, specifying 


retrieve information, or NO, specifying find information only. 


Output If the retrieve information field of the parameter list specified YES, 
DGTFARF1 updates variables addressed by the DABVAR fields. DGTFARF1 
provides a return code, as follows: 


Register states: R15 contains a return code and the ERNT is updated as 
described below. 





Return ERNT Field 
Code Name 


8 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 


12 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 
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DGTFARP1 Position Current Row Pointer at Top of List 


Function: DGTFARP1 positions the current row pointer at the top of the data 
set list array. The data set list array is an internal representation of data set 


names. 


Entry Point Address; ARVTPOS 


Input: Register states: R1 points to the parameter list described below. 


Parameter list 


Offset 


Hex (Decimal) 
0 


4 
8 

C (12) 
10 (16) 
14 (20) 


31-bit pointer to a 2-byte character variable set to 'NO' 


18 (24) 
1C (28) 


31-bit pointer to a 31-bit variable set to zeros 


Parameter 


31-bit pointer to a 32-bit parameter set to X'19', indicating 


which parameters are present 


31-bit pointer set to the value of CPPLARNM 


31-bit pointer to a 31-bit variable set to zeros 


31-bit pointer to a 31-bit variable set to zeros 


31-bit pointer to a 3-byte character variable set to 'TOP' 


31-bit pointer to a 31-bit variable set to zeros 


Output:: DGTFARP1 provides a return code, as follows. 


Register states: R15 contains a return code and the ERNT is updated as 


described below. 


Return 
Code 


0 
8 


12 


ERNT Field 
Name 


ERNTLMSG 


ERNTMODN 


ERNTPROC 
ERNTRC 

ERNTRSNC 
ERNTSERV 
ERNTSMSG 


ERNTLMSG 


ERNTMODN 


ERNTPROC 
ERNTRC 

ERNTRSNC 
ERNTSERV 
ERNTSMSG 
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DGTFARS1 Obtain Count of Data Sets 


Function: DGTFARS1 obtains the total number of displayable data sets from 
the data set list array. 


Entry Point Address; ARVTSTAT 


Input: Register states: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex (Decimal) Parameter 
0 31-bit pointer to a 32-bit string set to X'F', indicating which 
parameters are present 
4 31-bit pointer set to the value in CPPLARNM 
8 31-bit pointer to a 6-byte character variable set to 'RETURN' 
C (12) 31-bit pointer to a 7-byte character variable set to 'DISPROW' 
10 (16) 31-bit pointer to a 31-bit variable where DGTFARS1 will pass 


back count of displayable data sets 
1D (20) 31-bit pointer to a 31-bit variable set to zeros 


Output: DGTFARS1 updates the variable pointed to by the count field, and 
provides a return code as follows: 


Register states: R15 contains a return code and the ERNT is updated as 
described below. 


Return ERNT Field 
Code Name 


0 


8 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 


12 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 
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DGTFARUI1 Update Data Set List Array 


Function: DGTFARU1 updates columns for the entry in the data set list array 
pointed to by the current row pointer. 


Entry Point Address) ARVTUPDT 
Input: Register states: RI points to the parameter list described below. 


Parameter list 


Offset 
Hex (Decimal) Parameter 


0 31-bit pointer to a 32-bit parameter set to X'3', indicating which 
parameters are present 


4 | 31-bit pointer set to the value of CPPLARNM 
8 31-bit pointer to the DABL 
C (12) 31-bit pointer to a 31-bit variable set to zeros 


Output: DGTFARU1 updates the data set list array and provides a return code 
as follows: 


Register states: R15 contains a return code and the ERNT is updated as 
described below. a 


Return ERNT Field 
Code Name 


0 


8 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 


12 ERNTLMSG 
ERNTMODN 
ERNTPD 
ERNTPROC 
ERNTRC 
ERNTRSNC 
ERNTSERV 
ERNTSMSG 
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DGTFCTCK Verify Commands 





Function: DGTFCTCK checks the validity of commands in the CTAP. 
Commands in the CTAP must be enabled by DGTFCTSE before use. 


Entry Point Address; CTVTCTCK 


Input: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex (Decimal) Parameter 
0 31-bit pointer to a 31-bit pointer to the command line field 
4 31-bit pointer to a 31-bit variable set to the command line length 
8 31-bit pointer to a 1-byte character variable set to a blank 
(X'40') 
C (12) 31-bit pointer to an 8-byte character variable where 


DGTFCTCK will pass back the name of the load module which 
processes the named command 


10 (16) 31-bit pointer to an 8-byte character variable where 
DGTFCTCK will pass back the name of the command 


( - Output: DGFFCTCK updates the command routine (load module) and command 
4 name fields, and provides a return code as follows: 


Register states: R15 contains a return code and the following ERNT fields are 


updated. 

Return ERNT Field 

Code Name 

0 

8 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 

12 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 
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DGTFCTPR Process commands 


Function: DGTFCTPR gives control to the load module that processes input 
commands. You must create the CTPL in order to use DGTFCTPR. 


Entry Point Address; CTVTCTPR 


Input: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 
0 31-bit pointer to the CTPL 


Output: DGTFCTPR provides a return code, as follows. 


Register states: R15 contains a return code and the following ERNT fields are 
updated. 


Return ERNT Field 


Code Name 

0 

8 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 

12 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 
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DGTFCTSE Enable Valid Commands 


Function: DGTFCTSE, by updating the CTAP, enables all commands listed in 


the CTFU and disables all others. others by updating the CTAP. You must 
create the CTFU to use DGTFCTSE. 


Entry Point Address: CTVTCSE 


Input: Register states: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 


0 31-bit pointer to the CTFU 


Output: DGTFCTSE provides a return code, as follows. 


Register states: R15 contains a return code and the ERNT is updated as 
described below. 


Return ERNT Field 

Code Name 

0 

8 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 

12 ERNTLMSG 
ERNTRSNC 
ERNTSMSG 
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DGTFFOEI1 Obtain Input Information From the Screen Area Image 


Function: DGTFFOE1 obtains input information from the specified entry in the a 
list of data sets displayed in the screen area image. 
Entry Point Address; FOVTGTVL 
Input: Register states: R1 points to the parameter list described below. 
Parameter list 
Offset | 
Hex (Decimal) Parameter 
0 31-bit pointer to a 32-bit parameter set to X'F', indicating which 
parameters are present 
4 _ 31-bit variable set to the value of LPPLFOAD 
8 31-bit variable set to the value of LPPLARAD 
C (12) 31-bit pointer to the address of LPPLENT 
10 (16) 31-bit pointer to the DABL 
14 (20) 31-bit pointer to a 31-bit variable set to zeros. 
18 (24) 31-bit pointer to a 31-bit variable set to zeros. 
1C (28) 31-bit pointer to a 31-bit variable set to zeros. 
” 


Output: DGTFFOE1 updates the variables addressed by the DABVAR, and 
provides a return code as follows: 


Register states: R15 contains a return code and the ERNT is updated as 
described below. 


Return ERNT Field 


Code Name 

0 

12 ERNTMODN 
ERNTPROC 
ERNTRC 
ERNTRSNC 
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DGTFFOL1 Refresh the Screen Image Area From the Data Set List 
Array 


Function: DGTFFOL1 uses the data set list array to refresh the screen image 
area. 


Entry Point Address; FOVTLOAD 


Input: Register states: R1 points to the parameter list described below. 


Parameter list 
Offset 
Hex Parameter 
0 31-bit pointer to a 32-bit parameter set to X'3', indicating which 
parameters are present 
4 31-bit pointer set to the value of CPPLFONM 
8 31-bit pointer set to the value of CPPLARNM 


Output: DGTFFOL1 provides a return code, as follows. 


Register states: R15 contains a return code and the ERNT is updated as 
described below. 


Return ERNT Field 


Code Name 

0 

8 ERNTMODN 
ERNTPROC 
ERNTRC 
ERNTRSNC 

12 ERNTMODN 
ERNTPROC 
ERNTRC 
ERNTRSNC 
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DFP Common Services 


IGBDIS00 Call Device Information Services for UCB Address 


Function: IGBDISOO returns the address of the first UCB found for the generic 
device type passed as input. Whenever IGBDISOO provides return code 8, you 
must re-call the function, passing the same parameter list you used on the first 
call. Do not initialize any fields as indicated in the following instructions for 
making the first call to the service; make the second call with the parameter 
exactly as it is returned from the first call. The second call to IGBDISOO frees 
storage acquired by the function on the first call. 


Entry Point Address: CVTEXT2 + 12; resulting address + 36. 


Input: RO contains zeros and R1 contains a pointer to a pointer to the 
parameter list described below. You must create the parameter list described 
below; it must be 60 bytes long and you must fill in only the indicated fields; you 
must set the rest to zeros. You must also create a 32-byte problem determination 
area and a 25-byte return area, both initialized to zeros. 


Parameter list 


Offset 


Hex (Decimal) Parameter 


0 
6 
7 
8 


X'003C0100' 


x0 


~ X'00! (first call); X'02' (second call) 


3 1-bit pointer to return area 


C (12) 31-bit variable set to the return area length 


10 (16) 31-bit pointer to the problem determination area 


14 (20) | 3 1-bit variable set to the problem determination area length 


28 (40) | 8-byte character variable set to the generic device type name 





Output: 1GBDISOO provides the UCB address in the return area + 20, and, if an 
error occurred, updates the problem determination area. It also provides a return 
code as follows. 


Register states: R15 contains one of the following hex return codes: 0, 8 
(successful), 10, 1C, 20, 3C (unsuccessful). See DFP Diagnosis for a 
description of the problem determination area and details about the valid return 
codes and reason codes. 
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DFP ISMF Messages Available to External Applications 


The following messages are in the data set "SYS1.DGTMLIB’, with member 
names identified by the full message name minus the last character of the 
message name. For example, message DGTUVO05 is in 
*SYS1.DGTMLIB(DGTUV00)’ Likewise, message DGTUV016 is in 
*SYS1.DGTMLIB(DGTUV01)’ and so on. Each member contains 10 messages, 


numbered 0 through 9. 

DGTUVOO5 "ENTER Y OR N' ~-HELP= DGTMUVO5 -ALARM= YES 
"ENTER Y.OR N AT THE CURSOR POSITION 
DGTUVO06 "INVALID COMBINATION' -HELP= DGTMUVO6 ~-ALARM= YES 
‘ITF MAXIMUM NUMBER OF RETRIES=0 THEN SECONDS BETWEEN RETRIES MUST BE O 
DGTUVO07 "INVALID COMBINATION' -HELP= DGTMUVO7 .ALARM= YES 
"IF SECONDS BETWEEN RETRIES=0 THEN MAXIMUM NUMBER OF RETRIES MUST BE O 
DGTUVO 16 "MUST BE BLANK' -HELP= DGTMUV16 -ALARM= YES 
"AMOUNT OF I/O BUFFERING MUST NOT BE SPECIFIED IF DUMP IN COMPRESSED FORM = Y 
DGTUVO21 "SPECIFY ONE OR MORE' -HELP= DGTMUV21 -ALARM= YES 
"YOU MUST SPECIFY ONE OR MORE OF THE FIELDS BELOW 
DGTUVO024 'ISMF INTERNAL ERROR' »-HELP= DGTMUV24 -ALARM= YES 
'ISMF INTERNAL PROCESSING ERROR 

oe DGTUVO31 "ENTER 1 OR 2' »-HELP= DGTMUV31 -ALARM= YES 

{ "ENTER 1 OR 2 AT THE CURSOR POSITION 
DGTUV032 "RESET MUST EQUAL N' »-HELP= DGTMUV32 -ALARM= YES 
"RESET = Y IS INVALID IF ACCESS SOURCE DATA SET IN SHARED MODE = Y 
DGTUVO37 - - ALARM= NO 
' €LOGBUBNM (&LOGBJBNO) SUBMITTED 
DGTUVO038 aie -ALARM= NO 
"€LOGBJBNM PLACED IN &LOGBJBDS 
DGTUVO40 an - ALARM= NO 
"€LOGBJBNM ADDED TO &LOGBJBDS 
DGTUVO45 "€CURLIOP FAILED' »-HELP= DGTMUV45 -ALARM= YES 


"€6CURLIOP LINE OPERATOR FAILED DUE TO AN UNEXPECTED ISMF INTERNAL ERROR 


DGTUVO46 "€§CURCMD FAILED' -HELP= DGTMUV46 -ALARM= YES 
"&CURCMD COMMAND FAILED DUE TO AN UNEXPECTED ISMF INTERNAL ERROR 


DGTUV048 "COMMAND FAILED' -HELP= DGTMUV48 .ALARM= YES 
"EITHER THE COMMAND FAILED OR AN UNEXPECTED INTERNAL ISMF ERROR OCCURRED 


DGTUVO049 "MISSING VOLSER' .HELP= DGTMUV49 -ALARM= YES 
"AT LEAST ONE VOLUME SERIAL NUMBER MUST BE SPECIFIED 


DGTUVO050 "MISSING UNIT TYPE' .HELP= DGTMUV50 -ALARM= YES 
"UNIT TYPE MUST BE SPECIFIED FOR VOLUME SERIAL(S) 


Figure 46 (Part 1 of 3). DFP ISMF Messages Available to External Applications 
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DGTUVO5 1 "§CURCMD INVALID' .HELP= DGTMUV51 .ALARM= YES | Ke ; 
'"&CURCMD IS ONLY VALID WHEN ENTERED FROM THE LIST PANEL > 


DGTUVO52 "UNABLE TO FIND VOLSER' .HELP= DGTMUV52 ~-ALARM= YES 
'THE ACTUAL VOLUME SERIAL FOR THE INDIRECT VOLSER COULD NOT BE FOUND 


DGTUV053 ‘UPDATE OF LIST FAILED' .HELP= DGTMUV53 -ALARM= YES 
"BACKGROUND JOB SUCCESSFULLY CREATED BUT UPDATE OF LIST FAILED 


DGTUVO54 "INVALID STATUS' .HELP= DGTMUV54 -ALARM= YES 
"IF NO OUTPUT VOLUMES OR UNIT SPECIFIED, STATUS MUST BE OLD 


DGTUVO055 "MISSING DEVICE TYPE' .-HELP= DGTMUV55 -ALARM= YES 
"WHEN STATUS OF DATA SET IS NEW, AT LEAST A VALUE FOR UNIT MUST BE SPECIFIED 


DGTUV056 "MUST BE 3 OR BLANK' .-HELP= DGTMUV56 -ALARM= YES 
"WHEN REPLACE IF DUPLICATE REQUESTED, DO NOT RENAME DATA SET 


DGTUV057 "DUPLICATE DATA SET NAME' .HELP= DGTMUV57 -ALARM= YES 
"DUPLICATE DATA SET NAME INVALID FOR LIST COMMAND 


DGTUVO062 "PANEL PRIMING FAILED' .HELP= DGTMUV62 -ALARM= YES 
"UNABLE TO RETRIEVE SAVED PANEL VALUES - LAST-USE MODE IGNORED 


DGTUV063 "PANEL PRIMING FAILED' .HELP= DGTMUV63 -ALARM= YES 
"UNABLE TO RETRIEVE SAVED PANEL VALUES 


DGTUV067 "§CURLIOP INVALID' -HELP= DGTMUV67 -ALARM= YES 
"€&CURLIOP INVALID FOR A DFHSM MIGRATED DATA SET 


DGTUV068 "MIGRATED DATASET INVALID' .HELP= DGTMUV68 -ALARM= YES 
"DFHSM MIGRATED DATA SETS ARE INVALID FOR THE &CURCMD LIST COMMAND 


DGTUVO069 "TOO MANY VOLSERS' .HELP= DGTMUV69 -ALARM= YES 
"MORE THAN 255 DIFFERENT VOLSERS IN THE DATA SET LIST 


DGTUVO070 "&CURCMD JOB CREATED' -HELP= DGTMUV70 - ALARM= NO 
"BACKGROUND JOB SUCCESSFULLY CREATED FOR THE &CURCMD COMMAND 


DGTUVO7 1 "INVALID VOLSER' »-HELP= DGTMUV71 -ALARM= YES 
"VALID VOLSER REQUIRED TO PERFORM THE REQUESTED FUNCTION 


DGTUVO072 "ENTER REQUIRED FIELD' -HELP= DGTMUV72 -ALARM= YES 
"WHEN SPACE UNITS IS BLKS, A VALUE FOR BLOCKSIZE IS REQUIRED 


DGTUVO073 "ENTER REQUIRED FIELD' .HELP= DGTMUV73 -ALARM= YES 
"WHEN STATUS IS NEW, SPACE QUANTITIES ARE REQUIRED 


DGTUVO80 "INVALID DATA SET NAME' -HELP= DGTMUV80 -ALARM= YES 
"THE LINE OPERATOR FAILED BECAUSE IT WAS ISSUED AGAINST A BLANK DATA SET NAME 


DGTUV082 "BLANK NAME INVALID' .HELP= DGTMUV82 -ALARM= YES 
"BLANK DATA SET NAMES ARE INVALID FOR LIST COMMANDS 


DGTUVO083 "INVALID DEVICE TYPE' .HELP= DGTMUV83 - ALARM= YES 
"VALID DEVICE TYPE REQUIRED TO PERFORM THE REQUESTED FUNCTION 


Figure 46 (Part 2 of 3). DFP ISMF Messages Available to External Applications 
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DFQHAOO1 "RANGE O TO 999' .HELP= DFQHAOO1 -ALARM= YES 
"SPECIFY A NUMBER IN THE RANGE OF O TO 999 





DFQHA002 "RANGE O TO 13' .HELP= DFQHAO02 -ALARM= YES 
"SPECIFY A NUMBER IN THE RANGE OF O TO 13 


DFQHAO003 "MUTUALLY EXCLUSIVE FIELDS' »-HELP= DFQHAOO3 -ALARM= YES 
"CANNOT SPECIFY NO. OF DAYS OR NO. OF BACKUP VERSIONS FOR SYSTEM DEFAULT 


DFQHROO1 "INVALID VOLSER' .HELP= DFQHROO1 -ALARM= YES 
"CONTAINS INVALID CHARACTERS 


DFQHROO2 "ENTER REQUIRED INPUT' .HELP= DFQHROO2 .ALARM= YES 
"VOLUME AND DEVICE TYPE MUST BOTH BE SPECIFIED, OR SPECIFY NEITHER 


DFQHROO3 "INVALID DEVICE TYPE' .HELP= DFQHROO3 .ALARM= YES 
“THE DEVICE TYPE MUST BE 3330, 3330-1, 3330v, 3350, 3375, or 3380 


DFQHCOO1 "RANGE O TO 12' .HELP= DFQHCOO1 -ALARM= YES 
"SPECIFY A NUMBER IN THE RANGE OF O TO 12 


DFQHMOO 1 "INVALID HMIGRATE COMMAND .HELP= DFQHMOO1 -ALARM= YES 
"CANNOT BE MIGRATED TO LEVEL-1 FOR A TAPE ONLY MIGRATE SYSTEM 


DFQHMOO02 "INVALID HMIGRATE COMMAND -HELP= DFQHMOO2 -ALARM= YES 
"HMIGRATE CANNOT BE ISSUED FOR A LEVEL-2 TO A LEVEL~1 


DFQHMOO03 "INVALID HMIGRATE COMMAND -HELP= DFQHMO03 -ALARM= YES 
"HMIGRATE CANNOT BE ISSUED FOR A LEVEL-1 TO A LEVEL-1 


DFQHDOO1 ‘INVALID HBDELETE COMMAND' .HELP= DFQHDOO1 -ALARM= YES 
"THERE ARE NO BACKUP VERSIONS TO DELETE 





DFQCNOO1 ‘INVALID CONDENSE COMMAND' .HELP= DFQCNOO1 -ALARM= YES 
"CONDENSE CANNOT BE ISSUED FOR A MIGRATED DATA SET 


DFQCNOO2 ‘INVALID CONDENSE COMMAND' -HELP= DFQCNOO2 -ALARM= YES 
"CONDENSE CANNOT BE ISSUED FOR A TAPE ONLY MIGRATE SYSTEM 


DFQCNOO3 ‘INVALID CONDENSE COMMAND' -HELP= DFQCNOO3 -ALARM= YES 
"CONDENSE CAN ONLY BE ISSUED FOR A DATA SET WITH DSORG OF PS OR PO 


DFQCNOO4 'DSORG CANNOT BE OBTAINED' »-HELP= DFQCNOO4 -ALARM= YES 
"ERROR DURING THE OBTAIN OF THE FORMAT1 DSCB TO DETERMINE DSORG 


Figure 46 (Part 3 of 3). DFP ISMF Messages Available to External Applications 
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The following messages are not displayed on a line operator entry panel, but are 
written in the ISPF log as problem determination aids. ff 





DFQLPO0O1 'READ FOR DFHSM RECORD FAILED' .HELP= DFQLPO0O1 -ALARM= YES 
"THE READ FOR THE DFHSM CDS RECORD FAILED, SVC ERROR 


DFQLPOO2 'LINE OPERATOR FAILED' .HELP= DFQLPOO2 -ALARM= YES 
"LINE OPERATOR FAILED 


DFQLPO00O3 ‘READ FOR DFHSM RECORD FAILED' .HELP= DFQLPOO3 -ALARM= YES 
"THE READ FOR THE DFHSM CDS RECORD FAILED, DFHSM ERROR 


DFQLPO004 ‘SUCCESSFUL SUBMISSION' -HELP= DFOQLPOO4 - ALARM= 
'lineop LINE OPERATOR SUBMITTED SUCCESSFULLY 


KS 
tr 
oP) 


Figure 47. DFP ISMF Problem Determination Messages 
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DFP ISMEF Control Blocks Available to External Applications 





This section describes DFP ISMF control blocks available for use by external 
applications. Most control blocks are pointed to by fields in other control 
blocks. To find a control block, use the entry point name provided and find the 
control block whose name is equal to the first four letters of the given entry 
point name. The rest of the given entry point name identifies the field in the 
control block (identified by the first four letters) which contains the entry point. 


For example, the control block ARVT identifies the field GDRBARVT as its 
entry point. Following the rules stated above, GDRB is the control block that 
contains the entry point address for the ARVT in the field labeled GDRBARVT 
(offset 8). The GDRB lists register 10 as its entry point; therefore, you find the 
entry point for the ARVT in the field at location GDRB + 8. 


ARVT 


Entry Point: GDRBARVT 


ARVT 
Offsets Type Length Name Description 
ARRAY SERVICE VECTOR TABLE (ARVT) 
0 (0) CHARACTER 56 ARVT 
oo e 0 (0) CHARACTER 4 ARVTVID VISUAL ID: ‘ARVT' 
{ 4 (4) FIXED 2 ARVTLEN LENGTH OF ARVT 
6 (6) FIXED 2 ARVTUCNT USE COUNT 
8 (8) ADDRESS 4 ARVTBEG ADDRESS OF ARBEGIN MODULE 
12 (C) ADDRESS 4 ARVTDONE ADDRESS OF ARDONE MODULE 
16 (10) ADDRESS 4 ARVTADD ADDRESS OF ARADD MODULE 
20 (14) ADDRESS 4 ARVTCRET ADDR. OF ARCREATE MODULE 
24 (18) ADDRESS 4 ARVTDELR ADDR. OF ARDELROW MODULE 
28 (1C) ADDRESS 4 ARVTENDM ADDRESS OF AREND MODULE 
32 (20) ADDRESS 4 ARVTFIND ADDRESS OF ARFIND MODULE 
36 (24) ADDRESS 4 ARVTPOS ADDRESS OF ARPOSIT MODULE 
40 (28) ADDRESS 4 ARVTSORT ADDRESS OF ARSORT MODULE 
44 (2C) ADDRESS 4 ARVTSTAT ADDRESS OF ARSTATS MODULE 
48 (30) ADDRESS 4 ARVTUPDT ADDR. OF ARUPDATE MODULE 
52 (34) ADDRESS 4 ARVTTBLS ADDR. OF ROWID CNTRL BLK . 
56 (38) CHARACTER ARVTEND END OF ARVT 
CLCB 








Entry Point: LPPLCLCB/CPPLCLCB (LPPLCLCB for line operators, CPPLCLCB for commands). 
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Daa 
CLCB f 
Offsets Type Length Name Description Ne 


Re IED Te ED IEE RS EE TE CS SS SE SS SE ee ee tt eee GED RED EEE CUTTS ES CRUSE GES ETS ETS GEE ee HEUER ETT TS GEE CRETE OES GEESE GENTS iY Gen GUA CEES GOED GREED GSE: GEREN CUE ET SEVERE YD GUNA GERMS GEES GENS GEESE GEES GU CSUE GEESE GEES EEE GEES Gee ant SEUEED GOES GOED GED GEES GES GES ane eee ae oe 
2 LS ES EE A SS SRD CNS SND GLAS ETE UNE GUNS SEMES ORES CEN COVED CREE COTES ES SED GED GEES SRS NSS AES OSS OS NS SED SEE GED SPEED GOLREEED GEES GENTS GARIN) GEER GEES GUO CUES GS SS A IE SS SUD TE EY GES GSTS GS ES SEN GEES GEES GEIAD GUNES GREED EE Gee TD GD CS CEL SD GEE CHES GETS GEE GENET euET GEUER etEED GEER 


0 (0) CHARACTER * CLCB 

0 (0) CHARACTER 4 CLCBVID VISUAL ID: 'CLCB' 
4 (4) FIXED 2 CLCBLEN LENGTH OF CLCB 

6 (6) BITSTRING 1 CLCBFLG1 FLAG FIELD 

7 (7) BITSTRING 1 CLCBFLG2 FLAG FIELD 

8 (8) ADDRESS 4 CLCBNEXT ADDR OF ENXT CLCB 
12 (C) ADDRESS 4 CLCBPREV ADDR. PREV CLCB 
16 (10) CHARACTER * CLCBENT CLCB ENTRY 


CONH 
Entry Point: SELBCONH 
If you are using DGTFARF1, the CONHCNT field must be a 15-bit variable set to the number of DABs 


whose column values are used to search the data set list array. The CONHCONE must be a 31-bit pointer 
to each CONE associated with the CONH. 


CONH 
Offsets Type Length Name Description 
CONDITIONAL CONTROL BLOCK HEADER (CONH) 
0 (0) CHARACTER * CONH - 
0 (0) CHARACTER 8 CONHMAIN _ 
O (0) CHARACTER 4 CONHVID VISUAL ID: 'CONH' \ Pe 
4 (4) FIXED 2 CONHLEN LENGTH OF CONH = 
6 (6) FIXED 2 CONHCNT NUMBER OF ENTRIES 
8 (8) ADDRESS 4 CONHCONE (*) CONE ADDRESSES 
CONH 


Entry Point; CONHCONE 


If you are using DGTFARF 1, you must set the CONENAME to a column name as specified in the DAB 
associated with the CONE; you must set the CONECOND to either 'EQ' or 'NE', used when comparing 
the value in the variable pointed to by the DABVAR in the DAB associated with this CONE to the column 
values in the data set list array. 


CONH 
Offsets Type Length Name Description 
END OF CONDITIONAL CONTROL BLOCK HEADER (CONH) CONDITIONAL 
CONTROL BLOCK ENTRY (CONE) 
6) (0) CHARACTER 12 CONE 
0 (0) CHARACTER 8 CONENAME NAME OF COLUMN 
8 (8) CHARACTER 2 * RESERVED UNUSED 
10 (A) CHARACTER 2 CONECOND CONDITION 
12 (C) CHARACTER CONEEND END OF CONE 
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CPPL 





Entry Point: R1 on entry to command routine. 





CPPL 
Offsets Type Length Name Description 
COMMAND PROCESSOR PARAMETER LIST (CPPL) PASSES TO THE COMMAND 
ROUTINE 
0 (0) CHARACTER 88 CPPL 
0 (0) CHARACTER 4 CPPLVID VISUAL ID: 'CPPL' 
4 (4) FIXED 2 CPPLLEN LENGTH OF CPPL 
6 (6) BITSTRING 1 CPPLFLG1 FLAG FIELD 
Wigton ‘ CPPLSTD STD INVOCATION 
Pe oe Suente CPPLTEOL INVOKE AT END OF LIST 
oa le ee-8 CPPLTEOA INVOKE AT END OF APPLICAT 
-1 iba % CPPLLOFL ACTIVE LINE OPERATOR? 
acs ave CPPLSMSG SET SHORT MSG DONE? 
lms CPPLSCNM LIST GEN'D FRM CATALOG 
‘ ea CPPLSORT SORT FLAG 
bese ere CPPLFILT FILTER FLAG 
7 (7) CHARACTER 1 CPPLPNTP PANEL TYPE 
8 (8) ADDRESS 4 CPPLARNM ADDRESS OF FIELD W/ ARRAY 
12 (C) ADDRESS 4 CPPLFONM ADDR. OF FIELD W/ FORMAT 
16 (10) ADDRESS 4 CPPLCLAD ADDR. OF THE COMMAND LINE 
20 (14) FIXED 4 CPPLCMDL COMMAND LINE LENGTH 
24 (18) CHARACTER 8 CPPLCMD COMMAND 
32 (20) ADDRESS 4 CPPLCMAD ADDR. OF COMMAND ON LINE 
36 (24) ADDRESS 4 CPPLPMAD ADDRESS OF COMMAND PARAM. 
40 (28) ADDRESS 4 CPPLCSCB ADDR. OF CURSOR CNTL BLK IT 
MAY BE EITHER THE ADDR OF PCCB 
OR LPCB 
44 (2C) ADDRESS 4 CPPLCSCR CURRENT SCROLL AMNT ADDR. 
48 (30) ADDRESS 4 CPPLPSCR PREVIOUS SCROLL AMNT ADDR 
52 (34) ADDRESS 4 CPPLCLCB COMMAND/LINE OPERATOR CONTROL 
BLOCK CHAIN PTR 
56 (38) FIXED 4 CPPLERRW ROWID NAME OF ROW W/ERROR 
60 (3C) ADDRESS 4 CPPLCNAM ADDR OF CATALOG NAME 
64 (40) ADDRESS 4 CPPLDABL ADDR OF DABL 
68 (44) ADDRESS 4 CPPLMODA ADDR OF FILTER MOD NAME 
72 (48) CHARACTER 2 CPPLAPPL APPLICATION ID 
74 (4A) BITSTRING 1 CPPLFLG2 FLAG FIELD 
Venes Soe tene CPPLMCDF HSM = YES ? 
eas eee ese CPPLVOLF VOL = YES ? 
oe17 = 11771 * RESERVED, UNUSED 
75 (4B) CHARACTER 1 * RESERVED, UNUSED 
76 (4C) ADDRESS 4 CPPLCNTN ADDR OF THE NAME OF THE 
CATALOG NAME TABLE 
80 (50) ADDRESS 4 CPPLLMSG ADDR OF THE LONG MSG 
84 (54) CHARACTER 4 * RESERVED UNUSED 
88 (58) CHARACTER CPPLEND END OF CPPL 
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CTAP 


a 
Entry Point: CTABCTAP | ay 
CTAP 
Offsets Type Length Name Description 
COMMAND TABLE - APPLICATION TABLE (CTAP) 
0 (0) CHARACTER * CTAP 
0 (0) CHARACTER 8 CTAPMAIN 
0 (0) CHARACTER 4 CTAPVID VISUAL ID: 'CTAP' 
4 (4) FIXED 2 CTAPLEN LENGTH OF CTAP 
6 (6) FIXED 2 CTAPCNT # OF COMMAND ENTRIES 
8 (8) CHARACTER 28 CTAPENT(*) 
8 (8) CHARACTER 8 CTAPNAME COMMAND NAME 
16 (10) FIXED 1 CTAPTRUN MIN. # OF CHARACTERS USED IN 
TRUNCATION 
17 (11) BITSTRING 1 CTAPFLAG FLAG FIELD 
Ne Ses i igh toes CTAPST COMMAND STATUS 
ay eee pete CTAPIMED IMMEDIATE COMMAND 
ie A eT CTAPLIST LIST COMMAND 
gett lle | 1111 CTAPRSVD RESERVED 
18 (12) CHARACTER 8 CTAPRTNM COMMAND ROUTINE NAME 
26 (1A) CHARACTER 8 CTAPTENM CMD TERMINATION ROUTINE 
34 (22) BITSTRING 2 * FILL UP END OF WORD 
Constants 
Length Type Value Name Description 
END OF COMMAND TABLE - APPLICATION TABLE (CTAP) DEFINED 
COMMAND STATUS - 
Saas Gua Gumne Sanus Soe saan anees somes amar Saws sames GOnee GO Say SE SONS SON SMT AO SO Se Oe SS Oe Se oo Se oe oe oe oe Oe Oe et ee St eS ae Ae ee ee i - i Le A St  — Ke a aS a SS a VS vO = 
BIT 1 CMDENABL COMMAND STATUS IS ENABLE x J 
BIT 1 CMDDSABL COMMAND STATUS IS DISABL = 
CTFU 
Entry Point: Created by invoker of DGTFCTSE 
CTFU 
Offsets Type Length Name Description 
COMMAND TABLE - FUNCTION TABLE (CTFU) 
0 (0) CHARACTER 168 CTFU 
6) (0) CHARACTER 8 CTFUMAIN | 
0) (0) CHARACTER 4 CTFUVID VISUAL ID: ‘'CTFU' 
4 (4) FIXED 2 CTFULEN LENGTH OF CTFU 
6 (6) FIXED 2 CTFUCNT # OF COMMAND ENTRIES 
8 (8) CHARACTER 160 CTFUNMS 
8 (8) CHARACTER 8 CTFUNAME (20) COMMAND NAMES 
-_ 
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CTPL 


CTPL 
Offsets 


Entry Point: Created by invoker of DGTFCTPR 





Description 


Coed eraeherwuadharnandamnadananaty-onan-dieussaicermuthcsmmadhaandeammntiensmntamatbomediennstecasendeaanatimaataedtommdamnsadimnentcenntianasstaadth-amaleamndth-emdhaoeet ommadionssedhaaneadtaadianstecssediesnsds mma meni anmudaanedposed-asedheenediemmadharrahannadpanadkrsmkenardersdesasederedi-ndhasnuk-andiaand-nareticansel renal nasedecesnal emmetagaadhoedseeedhnenataanssadeaneteaadermadredaderseand 
(EF CURT Ce SS ED mC a ce ete eee en SE RES TED nem ene cee cD UE eee me eens cates a eS TD ES COTTE CEE REED CE cemeE enes emer SORRRD SAEED ARETE GCE GE ED GU ERS CURED ED SEEN CURE GEE GEETT GEUTS GENS ORAS SURED CUTE SUT QOUED SEED GENES GEES GED GED GEE EES OLED GENS GINED GEE GREE SEED ED GUE wom CUED amen 


(C) 
(10) 
(18) 
(20) 
(24) 
(26) 
(28) 
(2C) 
(30) 
(34) 


(38) 


(3C) 
(40) 
(44) 
(46) 
(48) 
(4C) 
(50) 





CHARACTER 
CHARACTER 
FIXED 

BITSTRING 


a eee 
eal 
CHARACTER 

ADDRESS 
ADDRESS 
CHARACTER 
CHARACTER 
ADDRESS 
FIXED 
FIXED 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 


ADDRESS 


ADDRESS 
ADDRESS 
CHARACTER 
CHARACTER 
ADDRESS 
CHARACTER 
CHARACTER 





FEHR HEPMONFOOHE— 


£ 


FENNEL 


CTPL 
CTPLVID 
CTPLLEN 
CTPLFLG1 
CTPLLOFL 
CTPLSCNM 


CTPLVOLF 


CTPLMCDF 


CTPLSORT 
CTPLFILT 
CTPLFLGU 
CTPLPANL 
CTPLARNM 
CTPLFONM 
CTPLCMDN 
CTPLCMDR 
CTPLCLAD 
CTPLCMDL 
CTPLERLN 
CTPLCSCB 
CTPLCSCR 
CTPLPSCR 
CTPLCNAM 


CTPLCNTN 


CTPLDABL 
CTPLMODA 
CTPLAPPL 
* 


CTPLLMSG 
* 


CTPLEND 


VISUAL ID: 'CTPL' 

LENGTH OF CTPL 

FLAG BYTE 1 

LINEOP FLAG 

SOURCE OF THE GENERATED LIST 
1 CATG,O VTOC 

VOLUME DATA REQUEST FLG 

1 VOLUME DATA REQUESTED 

MCDS DATA REQUEST FLG 1 MCDS 
DATA REQUESTED 

SORT COMMAND FLAG 

FILTER COMMAND FLAG 

FLAG UNUSED 

PANEL TYPE 

ADDRESS OF ARRAY NAME 
ADDRESS OF FORMAT NAME 

NAME OF COMMAND 

NAME OF COMMAND ROUTINE 

ADDR OF COMMAND LINE 

LEN OF COMMAND LINE 

ERROR LINE NUMBER FIELD 
ADDR OF CURSOR CNTL BLOCK 
CURRENT SCROLL AMNT ADDR 
PREVIOUS SCROLL AMNT ADDR 
ADDRESS OF THE VDEFINED 
CATALOG NAME 

ADDRESS OF THE NAME OF THE 
CATALOG NAME TABLE 

ADDRESS OF DABL 

ADDRESS 
APPLICATION ID 'DS', 
RESERVED 

ADDRESS OF LONG MESSAGE 
RESERVED 

END OF CTPL 


‘vo! 
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CTVT 


/ 
Entry Point! GDRBCTVT | ee 
CTVT 
Offsets Type Length Name Description 
COMMAND TABLE PROCESSOR VECTOR TABLE (CTVT) 
0 (0) CHARACTER 36 CTIVT 
0 (0) CHARACTER 4 CTVTVID VISUAL ID: 'CTVT' 
4 (4) FIXED 2 CTVTLEN LENGTH OF CTVT 
6 (6) FIXED 2 CTVTUCNT USE COUNT 
8 (8) ADDRESS 4 CTVTCBE ADDRESS OF PGM DGTFCTB1 
12 (C) ADDRESS 4 CTVTCEN ADDRESS OF PGM DGTFCTE1 
16 (10) ADDRESS 4 CTVTCIN ADDRESS OF PGM DGTFCTIN 
20 (14) ADDRESS 4 CTVTCTE ADDRESS OF PGM DGTFCTTE 
24 (18) ADDRESS 4 CTVTCSE ADDRESS OF PGM DGTFCTSE 
28 (1C) ADDRESS 4 CTVTCCK ADDRESS OF PGM DGTFCTCK 
32 (20) ADDRESS 4 CTVTCPR ADDR. OF PGM DGTFCTPR 
36 (24) CHARACTER CTVTEND END OF CTVT 
— 7 
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DAB 
Entry Point: DABLDAB 


The DAB must be created by the external application that uses it. Follow the rules in the tables below when 
using a DAB. 


Note: The DABRQST field of the DAB must always be set to X'80' 


Service Field Field 
Using DAB Name Value 


DGTFARF1 DABVAR _ 31-bit pointer to a variable containing the column value to use for the search (if 
this DAB’s address is contained in the DABL pointed to by SELBDBLI) or a 
31-bit pointer a variable where retrieved column contents will be stored (if this 
DAB’s address is contained in the DABL pointed to by SELBDBLO). Variables 
must be the same length as the value of DABCLEN. 


DGTFARU1 DABVAR _ 31-bit pointer to a variable containing information which is to be written to the 
data set list array in the column specified by DABCNAME. Variables must be 
the same length as the value of DABCLEN. 


DGTFFOE1 DABVAR — 31-bit pointer to a variable where retrieved column value will be stored. 
Variables must be the same length as the value of DABCLEN. 











DABCNAME Description DABTYPE DABCLEN DABVAR 
Restrictions 

whether entry is displayable 

DLINEOP Line operator history column X’01’ X’000A’ 

DOBJ Data set name X’01’ X’002C’ 

DALLOCUS Allocated used space X’11’ X’0007’ 

DDSORG Data set organization X’07’ X’0003’ 

DRECFMT Data set record format X’09’ X’0005’ 

DVOLSER _ Volume serial number X’01’ X’0006’ 

DDEVTYPE Generic device type X’OE’ X’0007’ 

DENTYP Catalog entry type X’01’ X’0001’ 

DUCAT Indicates user catalog or non-user X’13’ X’0001’ Must be ’Y’ or ’N’ 
catalog 

DMULTV Indicates multi-volume data set X’01’ X’0003’ Must be ’YES’ or ’NO’ 
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DAB 


Offsets Description f ™ 


EN) EE FSD SS SUE eR ED EE ETD SD SEER EE OAD EOE EEE CRED GD GARNETT UR SLED GED GAS GEES EE COR am HORA SED GWEN CSS CEES GREED SERENE FED GETS GENES GRTNE GETS GENES GD GERD LEED GET QTNED SNEED CRED GEER GETS ETE SUES Seem GREED TER SUT QTE CNR GEREES COED SAND SHEED ERED GENTS GIES GHEY SUES SERS GUE OMENS SUS HEED GE GED Game au 


TS em eee MaRS GERD cenES SEED GUEST Gm cmEES cramems GEMALRY GREWED SUPUES GETRED SUED MmNLLCY GENES GEC GIS Senet coments GUESS SEED GUD ON ES GOERS GES SOUT CONES GED EES GEE SUES GNU en GREED GEES GUNES CHE ES GENES GEES CETUS CONES SEED ED EES TE Ge StS COS GID GUND GREED EEE GEES GEE CERN GRKED GEES NUD CEES GEES GED Gains aumUD GunD emER GED GoD aeons come eee 
SS NE A LL EF A OE TS A A VS A SL SE SNS Se SRARD GOSS GUL SUSE SOENSD cmMAAAED GOMES GEES GEREED WULND COREED ORS GERD GET SUT GND SEED SEED GORD CREED CUEED GOERED CEE GENT SHES GARE GREED Ge GREE CEE ETERS GENES NT QUE QED GED GED CURD EDD GETED GED cE GENES GENE SEED CoE 


0 (0) 
0 (0) 
4 (4) 
6 (6) 
7 (7) 
8 (8) 
16 (10) 
| ie 
Pm hoe 
Some has 
17 (11) 
18 (12) 
20 (14) 
24 (18) 
Constants 


Length Type 


CHARACTER 
CHARACTER 
FIXED 
FIXED 


FIXED 
CHARACTER 
CHARACTER 


ie He ee 
BITSTRING 
FIXED 


ADDRESS 
CHARACTER 


Value 


— 


DABFS 
DABCNAME 
DABFLAG1 
DABRQST 
DABDISP 
DABEXT 

% 
DABTYPE 
DABCLEN 
DABVAR 
DABEND 


VISUAL ID: 'DAB' 

LENGTH OF DAB 

RETURN STATUS OF COLUMN NAME 
DAB 

FILTER STATUS OF DSN DAB 
COLUMN NAME 


REQUEST STATUS FLAG 
DISPLAYABLE STATUS FLAG 
EXTENSION DAB INDICATOR 
RESERVED, UNUSED 

DATA ATTRIBUTES FOR COL 
DATA LENGTH OF COLUMN 
ADDRESS OF VARIABLE 

END OF DAB 


Description 


DECIMAL 
DECIMAL 
DECIMAL 


DABRSO 
DABRS8 
DABRS 12 


DATA RETURNED SUCCESSFULLY 
DATA RETURNED AS NULLS 
DATA NOT RETURNED 


cvendnennalfsnnadatemnendharnsent anneal amnaedieamealnrnmatrcmanndieannadipansantansamtiatamsndammmnt-enanadranaatansenaieenselemnaaieamethaamndienasatassnsatbemnadmmend aad assed eunsnedemmendiemmndudhasetarenat manentieomanadiennadhsastammateramaaemnd nad assed eaamadanmadmmt cated anseadharunetaamsendeemmtamgnateamsabcennvh ments neal amaseutommmntamtaetpmamattutnengt naupendammndamarendpetieeadnementrammnbemevdbermandpaansdnaisandamadprensend errand 
Le A CE OD A A SS AD CE SENS GENES SENNA GEN GULL SOD GREED SUNT SANUS GORD RD CONE ETE SES SOND GORED COD GE CRD GOES AD DS NS ES SE ED CUTS NT ES EES SRE GS ES EN SARS GAN SNCS GET SEES GRE SEED CREE NENT MAS CEN CU RN SNEED RAED CED CEES SNES GARD GED GUNNS SUTIN SEND GNMETD GANENED GUUS GAETD GRED Gai <em> LD 


oS NS AD NS ES SE SND SND SEND GIT RT GUNS GONE GED GS GAS AMD ED GY CS SNE SRE GEREN GENES GORE GOS GREY RED GEES QUES GEES SEE GAREY CORES OTT SEED SELES RE CUE CY EL SED AD CEE OS GSES SD GES SURES NS ED ED GUNS SENN GAAS GED EENES GENS SENN GREED GORUET ATS SLRS GREED SCNT GO CUNY GENS GENS GED Chi GENE GENE CHET 
LP A A A TS TS LD ST NS NN NE SA SS SS SN ED SY ENG CTL ED SED CREED GENS GEEED GENS GED SND GUE ERD GET SS SE GLE SEES ED OS GD SEE GREED CHESTS GOED SE GARD GT GND SOS GED GREED SEE SAND SHEED ROE SA SED GENE SED ES GS ANNES SRD NT SS SR ED SP CEES SID GED GND SLED LIED SEY GED GEES eR 


DECIMAL 0 
DECIMAL 4 
DECIMAL 8 


DABL 


DECIMAL 12 


DABFSO 
DABFS4 
DABFS8 


DABFS12 


DATA NOT PROCESSED 

DATA PASSED FILTER CRITERIA 
DATA DID NOT PASS FILTER 
CRITERIA 

DSN NOT FOUND BY CVAFFILT 


Entry Point: The DABL must be created by the external application that uses the service that requires the 
DABL. For DGTFARF1, SELBDBLI points to the entry point for the DABL associated with column 
information used as the search criteria to locate entries in the data set list array. SELBDBLO points to the 
DABL associated with the column information to be retrieved from the entries in the data set list array that 
meet the search criteria. 


DABL 


Offsets 


 cavedhureenedhinennadoanecelamaatdhaewardareundieramandhanandemreedinanndlsasantiensendh aranatresnattersdnsusstessnantaatemndenset erat cseatasamdiementnaadaeandeumedanmatammnntanesttneedeect-annadimmantnmertonedtsed-maedeanandyananets se taere dl vende Tema reer Mere re A arene Ye veered eee Dremel eereeA canard rere Peet vonrDeeneredh sneered ned carenel erred reread ermeeeed eens erent anal meee ensaene ternal 
{eRe ORNEEY GRD CRIED GTEEND GRUUEED COLD WED AURD COREL pNEND HEARED GOED GOOCED CUNO GANS SOLED SEES GRAD ETS GEN CEUAD GONE GED GET SRN AE SND ARAN EES GED SEND SEY RRS GU UD CESS CATS SONS SENS GLEN SAD GOAN GS SA NS GSS GUAT AED GENS SAND GAUNND CRED GENE GMD CUED QING LEPED COEEAD COLNE MND CREED GANT AED GUND GUMS GN GD GEN GED SED GES Grae ewe 


Description 


SEF NTT GUT SEES ARE GAETED CEE SRS SNE MAINS ORES SERRE SLND GENRES SEC CULT SONNE SUNN GREP LORE GEES LIENS COED SOND GEELRD GREED GHRES SN SEE SED OUD SERED GUND GENE SONS ONES ENED CLES ANS GND AOS NS GEES SINNED SENS SN GED GREED GUMS GUNS GENE GUL GUTED CERES GEES GENES GUNIEE SRMIED MAVENS GEELID GNNOD GUE GEES GHIEES GSTS COREY SED GINA GUNES CUED Ghee Ulli cuutens GmAnED MEET 
LE AEE CD NS NY TEN RNNNE NUNES ORNATE SAREE MEAD GANAS GAELS URN CTD SIGS GLLND GORD GEREN GEE QEIUIY NN GSNRND SERGE GOOD CONS GRORGAS GUNES SEES GENER GANGES SEEN GNU GRAND GED SLMS GAD GENS ONIONS GERAD GAMERGD GED GEREN SORRES GONG SEED GUE GED CONEY GNNED CREED GORE CNETE NED GHEE GOD GEES SOUND GENS SHEED END GLAAD GUND ONS GUNED GUEND GHIED KAUNAS AOSD GENNES SiS GTED QOTEES OOD CORED 


CHARACTER 
CHARACTER 
CHARACTER 
FIXED 
FIXED 
ADDRESS 


DABL 
DABLMAIN 
DABLVID 
DABLLEN 
DABLNUM 
DABLDAB (* ) 


VISUAL ID: 'DABL' 
LENGTH OF DABL 

# OF ENTRIES IN DABL 
LIST OF DAB'S 











ERTB 


Entry Point: GDRBERTB 
ERTB 
Offsets 


Description 


senna feed amnendfenyandpaasammndiannandh anand enmndharenamndpammnasdpestrsudiaamand amend rare ranmaadivanssepmmvantpnnned-annamtimmanedpenand camtpemmandeumasteamneemnd accel mmanadpeneneeth manatp asset anand anced ssmathaantiamantemnenainnsedaematiemenlpeameatienm de amuadhaanedh remediamdnaedionsedhmatamdirmdyaaudhammalimmadt- emnativmsned auaatienaadarsatienmatensmmtcrmtsamlttmagalhneadinmtamaatbraaedinemeciaruatiamadianamedicamlimnntionmed 
SO CE CEE ARS SED CUED SEES SUT GED GETS eaeeD COTE GED CREED QE GETS ORD NNN EES eERR, SNES SEEDS meee cee GEES GES GNSS GEES GERAD eee comme Gomme SOE CORE GED GD GREED CEES StS: een ERE SHEED cme eeeme GED SENT cum ete GOTT MEETS CENTS Meeeee ED SEER cee eee ED ARE Gn eee SEE GE GENS CURE eure ciwee cEneD Game GREE Gee eRe ee EET ee 


ISMF ERROR TABLE (ERTB) 


- 08/15/84 


anand mandi mameedfpransnentpasemaendioanemedimnmetpanumti mmamentinanasantintemetti amma named siemedpanatentiempasntiomeund puma tmnt uaa penta hemennset saad annsartpentenntaramectaasnaat aceasta masatommed banned nasal aaalameehoanmalaanelanadl-assacdhsrunathamndaneedheasnath rrutpamatanandieaamalammadthamnatonandnmande ammaatpeaenteamantnmasdhaundiaaastaediesnanadll asartpemmdemseadth asad asceeteamathamndissmadhanustiansatiomademmsdh amadtematanseeed 
A TS AS SS ED SENS ED RED SS ED CNS SEED GS SNES GED GEE GRE GUE GOAN) GREED SUED CUED Glee enUES HUNTS GANS eS QE CORED CUEEE SESS SURETY ALE SUTTE CREEED GEASS SURES QUTEN GETE Gaends SEH GENES CERES CREE GAWD CEES GED SERED ONES GST AED SPER ED ENE REY CED OES GED GED GE GED SEVEN SE SLED GED GENES GEE MED TED UROST enue coe GEE SERED CD 


0 (0) CHARACTER 
0 (0) CHARACTER 
0 (0) CHARACTER 
4 (4) FIXED 

6 (6) CHARACTER 
8 (8) ADDRESS 
12 (C) ADDRESS 
16 (10) CHARACTER 
24 (18) CHARACTER 
32 (20) CHARACTER 
76 (4C) CHARACTER 


84 (54) CHARACTER 


ERNT 


a 
OPOWAFENNE 


— 
W 
NO 
© 


ERTB 
ERTBHDR 
ERTBVID 
ERTBLEN 
* 
ERTBBUFR 
ERTBCURR 
ERTBAPPL 
ERTBFUNC 
ERTBOBJ 
ERTBPNL 


ERTBENT 


ERROR TABLE HEADER 
VISUAL ID CONTAINS 'ERTB' 
LENGTH OF ERTB 

RESERVED UNUSED 

PTR TO LOG BUFFER 

PTR TO CURRENT ERTB ENTRY 
ISMF APPLICATION ID 
FUNCTION/DIALOG NAME 

LIST PANEL FUNCTION OBJ 
LAST PANEL DISPLAYED ERTB 
ENTRIES 


Entry Point: Before completing the ERNT, you must set the ERTBCURR field to the value of ERNTPTR 
(found in the current ERNT). The ERTBCURR then contains the entry point value for the ERNT. 


Length Name 


Description 


t cnsunlb eseetinamradhanunelimaumnieseusteansntinaaydl cmmetbmvmatiaanacsdnamedpemmmnipnasnadeonaadieeneet sump mmmadbnamatemecdcmmatbenanadmmadamatbmssadeamadknemadtenmathanssdnsdremadseamadnapadsassedlmeaeatmeamdenadsmahamndmpmaduncedeeedemmdiemanabapnantpanaadhaedhsiendemmadhasadicmnndhmutemnadt-aandteamedbamandimmatunads namaiammtbamnasteandtiannds nsentbamdammadthanmatnasnatemantmmpatitmeasdtenemntoemadimsasad 
ES NY ET EY LD NT NS GA SND ED GE NETS RED ERD ST ES ES SED SLES SSD SEEN CANES GET SE SS GEES CLE SD NES GENS EY SEL NEY MNES CRED EE SD SNS RS EE SEY OEY SS ED CD OED SS CREE SE NED SES SES ED OU SRS ET SEED CONN ED EE SRE GED CRN HIRD ELISE EEE TD GEN COUNTS SERED OED MARE COED 


Le cnt sesundibeusuatfantssnedpamenedpeamationaanadpananndperavanthennmdhaeaedparmeedinaundiranasdiearedhenvt rumadeasamslensastentanliemnmalvagnantsennntamsnttamantansedsemnciiammndsnscastmadteadamamibeersathemecdtemntmmnalbamedhaaamdsaanaansanatbenmatereadamnnethamnsdmmandimsasedhemndhoradaamnti unsealed rmautarentmnandlannsdanasadamadtbenammdsmassdentemnthcomadimmentiamadtiontestiennetveml ammntsmsnatvnsaateetenateuntammntcementarand 
A ED ANS ED A EEN ED GD SS CLS ES SE TES TS ED OAT EN SA ES SN GS ES MUS RNS SENS GEE OEE GREE TS SETS GEOT ERY SEEN NRE END GoD SE SES SD ED GUE GET CORED RLS ES ED SUE RD NE SED SEED GRRE GERD ED NE GTS ES SEED LS SHES CRE CNS EEE SEAT OEY ED ES ES ERE UNS SS ERE LOND URL 


ERTB 

Offsets Type 
0 (0) CHARACTER 
6) (0) ADDRESS 
4 (4) CHARACTER 
4 (4) CHARACTER 
12 (C) CHARACTER 
20 (14) FIXED 
22 (16) FIXED 
24 (18) CHARACTER 


28 (1C) CHARACTER 
36 (24) CHARACTER 


44 (2C) CHARACTER 

52 (34) CHARACTER 

87 (57) CHARACTER 
Constants 


Length Type 


ERNT 
ERNTPTR 
ERNTINFO 
ERNTMODN 
ERNTPROC 
* 

ERNTRC 
ERNTRSNC 
ERNTSMSG 
ERNTLMSG 
ERNTSERV 
ERNTPD 


PTR TO NEXT ERTB ENTRY 
ERNT INFORMATION 
MODULE NAME 

PROCEDURE NAME 
RESERVED UNUSED 
RETURN CODE 

REASON CODE 

SHORT MESSAGE ID 

LONG MESSAGE ID 
FAILING EXTERNAL SRVC 
PROBLEM DATA 
RESERVED, UNUSED 


Description 


td sensed erranesinananndi-emmensalhncanssaipannayudhansemaewseendpesanst aamadtenmmntaraemdbayemtrasmndiemareteranmataemtaraanat acaumtpenmetbeunnnal aundh-onandranmaticanmationsndh aeatmannthaneadh-ntandhaattmmantteemantonsmaieassdeennadpamredicmmaltamsandpanamediasantiamedemed anand namasdivassentsnasetsintenmsatnsunedptnmnadismaedpermpamnatinanmatssetaatiennadmmedeaniantammandpemantensnnalmaaedgeataniparamntpemesntpannaiateanvalpeiiaalptanamtpameansapantentpemanmianrnsead 
EE AAS ED UT ERS SD EEF ON CNS SD GENE EEE AED CLES ONE NNN SETS CURRY SED ST OURS SEED SD OD SE GME AND SELEY SEED GENT ETE Cmte GEE EE SEED GETS EY GN SS ES ES EY GS SRS SRD GE GES SEED ATEN SANS SEES GE SEEN GND SUED GREET LATED OLY Sut Gaim GED GOED GE Ge GY SAD GY GE eulttS GiNEtD GOLD GER amet cD etme 


 eadpenanadienathnsens imate qumendimnsnndoansteanuatasanatimmet appamapanmantraneantbmstaanmteemmedammtiaansteansetimmanteasaadiamndhamantizamedpanndlmmardiennedeannad- amd onmlmaadiecsatieeadh-mmatanamdbmansdansnadlmadh nae tasantinssssdmasnadicamadiananel-ammnltimaeticammmndhmuandaeadpanatbamendhgumntionaatcasateammatpemmnetmnsataranetemaned) staal mssanttpanieet eared aearratpmsaal aetententaedh eaertpaniamtpasmasaneatmantpravandpraent 
ATS CRE ND AS TT GOED GRE ATED GRES GENEES EEN GAD SS GLUES GSES SENS EE GD ED ES ES VIS ED EE SOND GD Se TY GANNTS GAR SS SE ET OS CE EEE SE ED GOED SEED GEN GED SES GUEZD GOED ORME STE SEED GOUT CEETD GED MNT GUNES GER SEND GERD Sot Sim Cae SEES WERE ONE ete COED GED GERED GUE eet GETS GED Ge ene ciety cmt 


2 DECIMAL 15 
2 DECIMAL 





1320 


CNTERNT 
LENERNT 





NUMBER OF ERTB ENTRIES 
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ET 


Entry Point: GDRBET 


Description 


. ssnseliprumerdnneredpamnreedieminedfanomtivendh neeeeh amend pruaedanmertimevacdinmanedianmnl-anadpanediansatiemane tamed sian nmedemendeamadpanneetiensaall canard sumed areatbnaentiaenndpataalasaneecsslinensdnaalammelcrdaansalarcent aemethansedjumenetisnanedhedarendboanclerantiernnalbnasadl onnall ammhannesienmndiaemediamesell vamedenaendienantanapumraedcnsudycamaliamnnlpenemaaveeadrannt cenedh-areacdnamdunavalpnermaaverrd oaedh casera naan 
A A TOT AE ON AON SY A I NT CE OND ARS NE AE EY SN SNE SY SET ACER SD SUN NTS LY SE SAD SAAN GONE ND STE SINS SEED NRA. OLE OND SOLE GOUT NS GREG GEE SENN SENET SUEUR GUNNS GREENS CRIED SORE GUI SENNDD GEARED GUEEA ONES NEN SAEED SEAT SRN GED EMD SED GaEED GERD GUUS GETEE OONIN CHUN MOUEER SINSED GREAD GEREN GIWED GUNN GEN CRON CUED 


VISUAL ID CONTAINS 'ET ' 
LENGTH OF ET 

RESERVED UNUSED 

LEVEL OF DFDSS INSTALLED ON 
SYSTEM 'NNVVRRMM'X WHERE NN 
IS 04 IF LEVEL COULD NOT BE 
DETERMINED VV IS VERSION RR 
IS RELEASE MM IS MODIFICATION 
LEVEL OF DFHSM INSTALLED ON 
SYSTEM 'NNVVRRMM'X WHERE NN 
IS 04 IF LEVEL COULD NOT BE 
DETERMINED VV IS VERSION RR 
IS RELEASE MM IS MODIFICATION 
6 CHARACTER VOLUME SERIAL 
NUMBER USED BY DFHSM TO SIGNAL 
MIGRATED NORMALLY 'MIGRAT' 
FMID OF ISMF 

ISMF COMPONENT ID 

VOLSER OF SYSTEM RESIDENCE 
VOLUME 

DEVICE TYPE OF SYSRES 
RESERVED, UNUSED 


Description 


ET 
Offsets Type Length Name 
ISMF ENVIRONMENT TABLE (ET) 
O (0) CHARACTER 52 ET 
0 (0) CHARACTER 4 ETVID 
4 (4) FIXED 2 ETLEN 
6 (6) FIXED 2 * 
8 (8) FIXED 4 ETDSS 
12 (C) FIXED 4 ETHSM 
16 (10) CHARACTER 6 ETHSMV 
22 (16) CHARACTER 8 ETFMID 
30 (1E) CHARACTER 9 ETCOMPID 
39 (27) CHARACTER 6 ETSYSRES 
45 (2D) CHARACTER 4 ETDEVTYP 
49 (31) CHARACTER 3. * 
FOVT 
Entry Point; GDRBFOVT 
FOVT 
Offsets Type Length Name 
FORMAT SERVICE VECTOR TABLE (FOVT) 
O (0) CHARACTER 84 FOVT 
0 (0) CHARACTER 4 FOVTVID 
4 (4) FIXED 2 FOVTLEN 
6 (6) FIXED 2 FOVTUCNT 
8 (8) ADDRESS 4 FOVTBEG 
12 (C) ADDRESS 4 FOVTDONE 
16 (10) ADDRESS 4 FOVTFIND 
20 (14) ADDRESS 4 FOVTGTLA 
24 (18) ADDRESS 4 FOVTGTVL 
28 (1C) ADDRESS 4 FOVTHIDE 
32 (20) ADDRESS 4 FOVTHILT 
36 (24) ADDRESS 4 FOVTHRD 
40 (28) ADDRESS 4 FOVTINIT 
44 (2C) ADDRESS 4 FOVTLAI 
48 (30) ADDRESS 4 FOVTLOAD 
52 (34) ADDRESS 4 FOVTMOVE 
56 (38) ADDRESS 4 FOVTPCSR 
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VISUAL ID: 'FOVT' 

LENGTH OF FOVT 

USE COUNT 

ADDRESS OF FOBEGIN MODULE 
ADDRESS OF FODONE MODULE 
ADDRESS OF FOFIND MODULE 
ADDRESS OF FOGETLA MODULE 
ADDR. OF FOGETVLA MODULE 
ADDRESS OF FOHIDE MODULE 
ADDRESS OF FOHILT MODULE 
ADDRESS OF FOHRD MODULE 
ADDRESS OF FOINIT MODULE 
ADDRESS OF FOLAI MODULE 
ADDRESS OF FOLOAD MODULE 
ADDRESS OF FOMOVE MODULE 
ADDRESS OF FOPCSR MODULE 


























60 (3C) ADDRESS 
64 (40) ADDRESS 
68 (44) ADDRESS 
72 (48) ADDRESS 
76 (4C) ADDRESS 
80 (50) ADDRESS 
84 (54) CHARACTER 


FfHPeEeEese 


GDRB 

Entry Point: Address is in R10 at all times. 
GDRB | 
Offsets Type Length 


FOVTPTLA 
FOVTPTVL 
FOVTOQCSR 
FOVTQURY 
FOVTTERM 
FOVTAREA 
FOVTEND 


ADDRESS OF FOPUTLA MODULE 
ADDR. OF FOPUTVLA MODULE 
ADDRESS OF FOQCSR MODULE 
ADDRESS OF FOQUERY MODULE 
ADDRESS OF FOTERM MODULE 
ADDR OF FOFXAREA MODULE 
END OF FOVT 


Description 


C cettid ened ened nce auendlamanetien mand xnamatemend many Arasenalnsadenmnedcrasaalmnaslaaneath pnb cedlenaeecEramaadaaYemendaeseshammedh assent aedpameediomentrcnasd aa ahsmmeetemnsetenadieaaad aaapehvamaat asset oaadh ate maeteuneataehenmal anes) ona raaaaharand-onvdegmmaenssat ant oadkersedpisevmiamandaancalh oadenmundbevnnaamnnsdenuamaleranndvmratbammnd-amatiasaatvrmsedianmdtanndlassadbametseenanbunaedieaaasatcnemad 
LF TS NS A TE TN SA SS AS AAS ED AED ST CRD SEED GUTS GEC GOD GUMS GEES GUNES CURED GANS STE GREE GEE GUNES GENS GENTS CEES GREED GUND QEUUS SERED GENRES GENET GOUUS GEES GED SANE CURE GREED CREE GEES SNUTER GUEST CREED MASSE EEE GES GE UE EEE GES GEE SECU QEET SURE CHD COED Gon CEES GREED COED GEE GURAD EES WEEE GERD GENET Game GHD SHED GOED Roe 


0 (0) CHARACTER 96 
0 (0) CHARACTER 
4 (4) FIXED 

6 (6) FIXED 

8 (8) ADDRESS 
12 (C) ADDRESS 
16 (10) ADDRESS 
20 (14) ADDRESS 
24 (18) ADDRESS 
28 (1C) ADDRESS 
32 (20) ADDRESS 
36 (24) ADDRESS 
40 (28) ADDRESS 
44 (2C) ADDRESS 
48 (30) ADDRESS 
52 (34) ADDRESS 
56 (38) ADDRESS 
60 (3C) ADDRESS 
64 (40) ADDRESS 
68 (44) ADDRESS 


FREHRKEEFHEHKHEPHEEPHKPHKEHEEPHEKFEHEPHRPEHPENNE 


72 (48) ADDRESS 
76 (4C) ADDRESS 
80 (50) ADDRESS 
84 (54) ADDRESS 
88 (58) ADDRESS 
92 (5C) ADDRESS 


IMTT 


GDRB 
GDRBVID 
GDRBLEN 
x 
GDRBARVT 
GDRBASAB 
GDRBCTAB 
GDRBDAAB 
GDRBDSAB 
GDRBERTB 
GDRBET 
GDRBFOVT 
GDRBFSAB 
GDRBFST 
GDRBIMTT 
GDRBLLBL 
GDRBLPAB 
GDRBMDAB 
GDRBPVT 
GDRBSCT 
GDRBSRVT 
GDRBTPTT 
GDRBISPF 
GDRBCTVT 
GDRBDCMD 
GDRBDEVT 


VISUAL ID CONTAINS 'GDRB' 
LENGTH OF GDRB 

RESERVED 

ARRAY SERVICES VECTOR TABLE 
ARRAY SERVICES ANCHOR BLOCK 
COMMAND TABLE ANCHOR BLOCK 
DATA ACQUISITION ANCHOR BLK 
DATA SET ANCHOR BLOCK 

ERROR TABLE ADDRESS 
ENVIRONMENT TABLE 

FORMAT SERVICE VECTOR TABLE 
FORMAT SERVICE ANCHOR BLOCK 
FROZEN STORAGE TABLE PTR 
INTER MODULE TRACE TABLE 
LOAD LIST BLOCK POINTER 
LINE OPERATOR ANCHOR BLOCK 
MAIN DIALOG ANCHOR BLOCK 
PROFILE VARIABLE TABLE 
STORAGE CONTROL TABLE PTR 
SERVICE ROUTINE VECTOR TBL 
TRACE POINT TRACE TABLE PTR 
POINTER TO ISPF 

POINTER TO CTVT. 

PTR TO ZTRAIL TRUNC REMAIN 
PTR TO DEVICE TYPE TABLE 


Entry Point: Before completing the IMTT, you must set the IMTTCURR field to the value of IMNTPTR 
(found in the current ERNT). The IMTTCURR then contains the entry point value for the IMTT. 


Description 


SS nS tn ED ED ARN CEE EES GHEE ANE UTED GED GAN SET CRED GEES LOT GHD SUEITS AOD GEES GANS SEES GSES CanEteT GieRID CRUE GEES GEMANGS GS GETNS GEES GEES ERAND GREE GOED CREED GREED GENOEE GRAND GNP SEED GED QUE SOUND GUROIT URI GEEEED GMRAEP COND CRGRS GEES GENS FREED CORES GEES SRW ITTY OREELT GEES GREY GATE CHET SONU CRISED ENED GE AEE CHORD SOMME AeRUAD GND Geil QuNED eT 
SORE SD SEES OE UD ED EES GA AED EES RS GRD SEEN GOST GND SEEN RT ARES Ci GEES REE GREE Sees SEES GOED cRmED GREE couTES Gem Gamme SONY GOTID GERD ERD NSE HET SUED GREED GERD EEE QUT GEST GREED GmeEe GEE SLES ikteD GEEED GETS GEER GESTED GRE SEAT GEREN REY GENS CURED SARE GERD GENTS GOED ORES MED GED MINED CORT GREE GUI SET SENG GENE, GUS CMe eRtED met 


Se GOED ED CRY UNNETY ENED GOED GOA UNS GENES GREE ty SURED ED GEENS GED GESTS GEES GREED GOED SEL SEED GUNES ONES SUES GEES GEES Sete Gene GEE SERN Geeane SEED ce RED COND cee GLUED GEDES GENES GREED NEED CARES GEEED CRED GEES GLEE GAN GOURD CURED GREED GEELED GLEE SHURE GUUELS “HELEY EES GARD CULES Mee GREED GUESS COMED GARE AARON GEE GOWEE GENEP antEe Lm annED SEDO “EINe oOnne eoumE 
ee TS NES ND ENTS RED ED CARNE CREE SED GER ERS CTD ED GES GED EET EEE CAND UES OUD CEES GEES GEES SEE GREED ERED cee STD OEE GEES GRUED SeteES CREED GEREED OED ante eRe GEDEED GREED GREE ERED GRASS EEE CEE ERSED GEEEDS GUUS CRUEED CRED GERD GEES CED GEEAD MRE GRMEAE CTH: GREED GUTEED GARD ClmeD GENT CEE CURED CUED SAEED GTS OTETD GENTS EERE KEES SiN oor ED 


INTER MODULE TRACE TABLE HDR 
VISUAL ID CONTAINS ‘IMTT' 
LENGTH OF IMTT 

RESERVED UNUSED 

POINTER TO THE CURRENT ENTRY 
RESERVED UNUSED IMTT ENTRIES 


IMTT 
Offsets Type Length Name 
ISMF INTER MODULE TRACE TABLE (IMTT) 

0 (0) CHARACTER 6288 IMTT 
0 (0) CHARACTER 16 IMTTHDR 
0 (0) CHARACTER 4 IMTTVID 
4 (4) FIXED 2 IMTTLEN 
6 (6) FIXED 2 * 
8 (8) ADDRESS 4 IMTTCUR 
12 (C) CHARACTER 4 * 
16 (10) CHARACTER 6272 IMNTENT 
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IMNT 


Entry Point: IMTTCURR 


anrmsdpunsinintparianertiwasvesdiinatouioanncedinnsienrtpesenedpsaisaindpuasandpanamadaraenthemendpanreutemrsendaneandenantieannduienelemtaataacndassnadpameitasmenthparahalreanndpmvetyseaadpiantndpanietedmsnalascandnerendeasertapeinntmanadhaaret comand annsedpannetaraseaheaatdnnntadetennalemaa apnea ersceiesenedeanneadanteteAprend)-ansadpimmndananedaanatedvormadnanusapennalbenumedpenmndynertdoasnadramantennnalparnedvencentpmandamatpuntndpivinndvernsdaasenDennasiameemensand 
RED CENT CONTE SUID CIEE EEE EUAN ONE) CEUED ONED SEED CHET GUUME TENE Cae CURES HED SENNS SUED OPED NUD CED SUSY GUNES GEES CLINE SEARS CES GREE SONS GREED SATS GERS! ORE SEED GEES MUENE GENES SORNRE CRETE GED GHEY SRD) GUD SEED GAAS GUND CRAND GEET GEENT GULE GENS GREED GEE SEES SRT CHD GEKID SENT SHEEP CUNTe COED GETNP GHETE CUSED GUERE. GREED GHERS TED SIDED HUD GENE GERID GULIND GREP 


 savundfermnlinasatdr-eaeelpenaredbennntammediavanndpraneeliecamabeaseutssmalymunidennedtrnsndp- asad auedbareusth nmarkeiantnaadh aannah-snnsadrrandpremndhanonthnearst-araahassnatimvuntassendhasanthanedtmnaaadcnssd-ancdeerasadhnnasdassenthasamtannadharcudiesnendanakammnadtnandth-sadhamsndpamanadimastescedt-sanasdapnatasuiadvmsednteanr dh anal mast neanedhnetatanande-rnasd anand menadinaneivetaad anal nssepesnutromedpimndunniatensusatesreadlreanin’ 
SURE CURED GE ERR QED FEENES CETED CNET CUTE GHEE CrUENS CERIN GREED GEAR CUE CHUN GUND GHNDED GENES GLEN GAEND GED GENTE GENEID CORED GOMES GED CRETE GEES GENES GRAIN GREE? GENE SED EES GEUEES GED GREE EENED SOEWE GUESS SEMIS GENES GEES SEDUT CEE GATED EEUED GEEUT GEIS GREE) GUNES GREE GEES SUG GUE GENS GOED COEES GENIE OONTS GEE PETE GHNUED COENS GRAUD GUTED GEE GNM QUNUD GONE WENED CONED GHETD GERD 


IMTT 
Offsets Type Length Name 
IMTT ENTRIES 

0 (0) CHARACTER 56 IMNT 
0 (0) ADDRESS 4 IMNTPTR 
4 (4) CHARACTER 52 IMNTINFO 
4 (4) CHARACTER 8 IMNTEMID 
12 (C) ADDRESS 4 IMNTREG1 
16 (10) ADDRESS 4 IMNTREGB 
20 #£(14) CHARACTER 35 IMNTUSER 
55 (37) CHARACTER 7 * 

Constants 

Length Type Value Name 


[oJ puenmdhaeedhananall-camalhecvveabennsntemmndpornendhasasall-ansssdthansendh setaramtradranradkenandiamnutmmmtamadseneAasusalt- aneatinamatpdumatssadkemuntesenatemart-naaEnatanaceds-arnadkomestiansmaadlaadhcenadesarialamastenmebanutamsaahenceerdmaanlamadttnaadbamandimamd-mssatimieenabaee.edisnssdhensredhemesdaamaadpanmeatesessunbeansadinamatbasaandscansedrancekeammtedsdemmanh-reskenenahamanteconamieeneedemedeunnadisuneatemesdrarvoed 
AO CE SNE CHD EES ANN GAMES TED AER SES GED SD GED SEND SHLD GND REA GENES GEREED SREY CITE SURED GREE ENTE GEE GENET SRD GEES GUNES GUE GENTE SIRE GREE GENES GREED GETS SUED GLAS GRRE SEEN USTED SORES CNS GUEED GEES TY SE GUNES GREENS GRSD SOULS GRE GENES EEE GOREN GLEOHE CEO CUED GREE SUE SND GEE GETS GENET GUST WGN GREED GEES GEE GHUED CLUES QUE GEENEED GED CENCE 


ScnedheveseUfunaeandhcorrnndammvedhensenedioummedrsaansedianssandynssmnthrmnenthareuadnnndhamsstaeraadenpnatieamsahumansdnnaadenesa tase aumatemadbeanaselanmadunekvenasdhemenah-aamtqumadeonadnamademadhamadpapaud nnaudhocnd-neantammadbameed- ssa nsnatomnadmamadbaamaat eased asehemnmdeanabearundetersadsnanadimnmmalh asta aveadh-ouad-onaadhamaabbmenadpemceedprianetaantedissdrnmdpaeamd-naces mma samaantpanaadliesesmteantaandeesaedcaanet em 
ED OND GENES ED CONS ET NN AS SD SN GNA SEED GREE GENS CRED GOED CUED CUED GURY GARSD GERAD GOERS GET SEEN Gut eaySnAS GEES GLARED GUUS GTS cent ENS GED OWED GUND QD SAERAED GRR GUEND GUUND QED CREED EES SESE CUE CES SERRE GEES ENUTT SETS OED GERD CEE GENE UNE COD COED CUES GLNETE CUAND GENS CUTE GUNNS CARED GEES GEE GES Cl GD GOED GY ae GENS ORES UE 


(cme Ifpesaraand avenrusdh nama usevadieemarndpeanasedp-amnaedpuassetparenentvarmmmatioae dpuveesedpeemastinanasdmment emt aanatraemleradamaratanuntvennendneuedanseat amarante bemanlpeaemnasenats amatianaraderenadeeene apenas danmmndmanelaaaataateratianasleemetvaamalemendyeedh aman tami iteendaemeed panera mamdanentpeannedroaaalpnamndpmnsaieauedenrendvemmadpaamandpenssinalpseaevelpemmad panna pantie dpeamsdpansantpamradpsanmntnsaninimanadanaeatrnanaienaed 
ed 


2 DECIMAL 112 CNTIMNT 
2 DECIMAL 6272 LENIMNT 
LOGB 
Entry Point; ERTBBUFR 
LOGB 
Offsets Type Length Name 
ISMF LOG BUFFER (LOGB) 

0 (0) CHARACTER 236 LOGB 

0 (0) CHARACTER 4  LOGBVID 

4 (4) FIXED 2 LOGBLEN 

6 (6) CHARACTER 2 * 

8 (8) CHARACTER 72 PGMLOGO8 

8 (8) CHARACTER 8 LOGBAPPL 
16 (10) CHARACTER 8 LOGBMODN 
24 (18) CHARACTER 8 LOGBPROC 
32 (20) CHARACTER 8 LOGBPNL 
40 (28) CHARACTER 8 LOGBSERV 
48 (30) CHARACTER 8 LOGBJBNM 
56 (38) CHARACTER 8 LOGBJBNO 
64 (40) CHARACTER 8 LOGBSMSG 
72 (48) CHARACTER 8 LOGBLMSG 
80 (50) CHARACTER 11. PGMLOG11 
80 (50) CHARACTER 11 LOGBFUNC 
91 (5B) CHARACTER 1 * 

92 (5C) CHARACTER 44 PGMLOG4S4 
92 (5C) CHARACTER 44 LOGBOBJ 
136 (88) CHARACTER 54 PGMLOG54 
136 (88) CHARACTER 54 LOGBJBDS 
190 (BE) CHARACTER 2 * 
192 (CO) CHARACTER 8 PGMLOGO4 
192 (CO) CHARACTER . 4 + LOGBRC 
196 (C4) CHARACTER 4 LOGBRSNC 
200 (C8) CHARACTER 35 PGMLOG35 
200 (C8) CHARACTER 35 LOGBPD 
235 (EB) CHARACTER - 1 * 





Description 

PTR TO NEXT IMTT ENTRY 

IMNT INFORMATION 

MODULE ID 

PARM LIST REG REG 1 

CURRENT WORK AREA ADDR 

USER AREA 

RESERVED, UNUSED 

Description 

(IMTT) 

NUMBER OF IMNT ENTRIES 

Description 
-_ 
a 


VISUAL ID CONTAINS 'LOGB' 
LENGTH OF LOGB 

RESERVED 

VARS WITH LENGTH OF 8 
ISMF APPLICATION ID 
MODULE ID 

PROCEDURE ID 

LAST PANEL DISPLAYED 
NAME OF FAILING SERVICE 
SUBMIT JOB NAME 

SUBMIT JOB NUMBER 

SHORT MESSAGE 

LONG MESSAGE 

VARS WITH LENGTH OF 44 
FUNCTION/DIALOG NAME 
RESERVED UNUSED 

VARS WITH LENGTH OF 44 
LIST PANEL FUNCTION OBJ 
VARS WITH LENGTH OF 54 
SUBMIT DATA SET NAME 
RESERVED UNUSED 

VARS WITH LENGTH OF 4 
RETURN CODE 

REASON CODE 

VARS WITH LENGTH OF 35 
PROBLEM DATA 

FILL UP REST OF WORD 











LPAP 


Entry Point: LPABLPAP 


LPAP 


Offsets 


creralfsnanadianmndl runedinasnsdh maamadirarundbamaastpsammetienmutieansnt aes ammtbanimtvanandivanetiamnatmmmntensath osmndetumtammedanmstmratbeusnatvaaatiramattensmtpsaaadamtamandiernsmtmmatiomsadlicaned) mmatemmetmassedhsmandamttessadksandtansadiernadiaadiarandpasmtprapaedcaleammdbamsatcrunsdlmmatannatieanpdhemanteadmmedonseadicssenal-muntsmamndimmmdteausll arusedemtrenadiammadmamndarrninnmel aamdbamantrnaantaned 
a KS STN A TE ED COE STE AERSE SED SENS ONES GrmES EEE SUS GUESTS ES SENS SE CR ED OES GUD Meme SE OOD Gn GED EE GEES GS SOND ORS eS cD TED SD GS EEEEE CEES See CUTE EES GRD Get RE GREED mS Sree SEED eee Com SUD Ge cee cee GREED eS cD EE GRD Gee ee GT Cee mS ee SS ED ee eee Gunes es 


Description 


 sensdierepatchacvureli suntiecsnndiemnped avuadissemdamedhapenaliaacdaredepmattmssmntesmadiamataamgadbausaadbenaaediametiamadttansnd aeeedinemadmnnetpamndioaaeattancademad ant ssendiemmmdsamedonssud,-aaadpamatvesssdsasendhnamdbammedtnaadhenadhaedeensadheamladaanadienaabaaediemiummadtnanaiaadtamnationsertiasudl aatamadioasadl-amadh-mananmendiasarediaamdtiecmtmendtnanandaaedmmndiensnal namathanatbammntemssasdaaed 
ee NS SE ENS CRU SD SE ASRS ED STS SERS REED SEES EE SS Cm OE SS GD OES OLED ERE GSE SENS STEMS RES GSD URES GERD GSTS SEES GES GY SRS SEED GOED GERD ENTS SERRES GEES SHRED GENT SSS CD ED NED eee eS GEE EONS en SEE TEED URED Stree CREED GES ES SD eTETS OEE Cate GEE SEY wm: EE GUS GED eat” GD eES GEES ED GUE 


NWDAHNLOOWO 


—) 


7 


28 


LPCB 


CHARACTER 
CHARACTER 
CHARACTER 
FIXED 
FIXED 
CHARACTER 
CHARACTER 
FIXED 


CHARACTER 
CHARACTER 
CHARACTER 


-MONN FO * 


CO © W 


LPAP 
LPAPMAIN 
LPAPVID 
LPAPLEN 
LPAPCNT 
LPAPENT (*) 
LPAPLONM 
LPAPTRUN 


* 


LPAPRTNM 
LPAPTENM 


VISUAL ID: 'LPAP' 
LENGTH OF LPAP 
# OF LINE OPERATORS 


LINE OPERATOR NAME 

MIN. # OF CHARACTERS USED IN 
TRUNCATION 

RESERVED, UNUSED 

LINE OP ROUTINE NAME 
TERMINATION ROUTINE 


Entry Point: LPPLLPCB (line operator is invoker)/CPPLCSCB (command is invoker) 


LPCB 


Offsets 


 crasadipnvusatfensnadi aneeandiaemeveliomanelhetoendl evamsatfensmsdvementipesensatiumadiaamtpeveticmtivementhaameedpemmatimnamtbeaandteamanteammnteasandtivemnctonmendimannalsscath-creedreedicuanatsanmadiemredi amma ousaataentpamuntumesstenadyasmmdpmesmdeaeuataaaad mensinreasdmaenteamadpament pense aathaamndpanpamtbnansat-assd-qmantpnandavnedamatpamntemmmdeenrmatperasniatpeenataesantamnmat immediate npmndimmanndpmnneatiasssentnmemtbanrantncnsdvemmantvatrand 
SD Gene. ED TD LAY GENE SURRY GATED GRRE HREM CUD CED GET? OES GED Le SEES ED GED GETS GARY GED GD QUES? END GENES GEES COONS GRD GET SORES GOED GEARS eee CERES GENE GUD SRLS GREE UE CED CURED GEES REED GERD CEE SEND GUNN CREED ENED GEES URED GELS GED GENE CON STEED ENED GED ERD GREED OULD GMERD GEREN ETE GRRLTD GED Cay GEE CREUD GAD aE GOT COVED ane 


Length Name 


Description 


CHARACTER 
CHARACTER 
FIXED 
FIXED 
CHARACTER 
CHARACTER 
FIXED 
CHARACTER 
CHARACTER 
CHARACTER 
FIXED 
FIXED 
CHARACTER 





NMOFPONNMNHHNHN FO 


LPCB 
LPCBVID 
LPCBLEN 
LPCBENO 
LPCBMFG 
* 
LPCBMLN 
LPCBCTG 
* 
LPCBAREA 
LPCBRND 
LPCBOFF 
LPCBEND 





VISUAL ID: 'LPCB' 
LENGTH OF LPCB 

ENTRY NUMBER 

MULTI LINE ENTRY FLAG 
RESERVED, UNUSED 
MULTI LNE ENTRY INDICATOR 
COLUMN TAG 

RESERVED, UNUSED 
AREA NAME 

ROW ID NAME 

OFFSET WITHIN AREA 
END OF LPCB 
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j 
| 
| 
i 
| 
U 





LPPL 


Entry Point: R1 on entry to line operator routine 


LINE OPERATOR PROCESSOR PARAMETER LIST 


Length Name 


LINE OPERATOR ROUTINES 


fo 
\ . 
"Sogou 


Description 


’LPPL 
Offsets 

0 (0) 
0 (0) 
4 (4) 
6 (6) 

lee 

Peas ier 

Alize 

| 
7 (7) 
8 (8) 
12 (C) 
16 (10) 
20 (14) 
28 (1C) 
32 (20) 
34 (22) 
35 (23) 
36 (24) 
40 (28) 
44 (2C) 
48 (30) 
52 (34) 
56 (38) 
60 (3C) 
64 (40) 
68 (44) 


CHARACTER 
CHARACTER 


FIXED 


BITSTRING 


wes 
sceilie 
se 


BITSTRING 


ADDRESS 
ADDRESS 
ADDRESS 


CHARACTER 


FIXED 
FIXED 


CHARACTER 
CHARACTER 


ADDRESS 


ADDRESS 
ADDRESS 
FIXED 

ADDRESS 
ADDRESS 


ADDRESS 


CHARACTER 


Po oNMhORKEK 


fFEHEEHHL 


a 


CHARACTER 
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LPPL 
LPPLVID 
LPPLLEN 
LPPLFLG1 
LPPLSTD 
LPPLTEOA 
LPPLTEOL 
LPPLLOFL 
LPPLLAST 
LPPLSMSG 
LPPLSCNM 
LPPLHIDE 
LPPLFLG2 
LPPLARAD 
LPPLFOAD 
LPPLCLCB 
LPPLLO 
LPPLROWI 
LPPLENT 
LPPLCMDF 
* 


LPPLCNAM 


LPPLLAIA 
LPPLROWA 
LPPLLAIT 
LPPLLPCB 
LPPLCNTN 


LPPLLMSG 
* 


LPPLEND 


VISUAL ID: 'LPPL' 

LENGTH OF LPPL 

FLAG FIELD 

STD INVOCATION 

INVOKE AT END OF APPL 
INVOKE AT END OF LIST? 
ACTIVE LINE OPERATOR? 

LAST USED MODE? 

MSG ID SET IN ERTB ? 

LIST GEN'D FR CATALOG 

HIDE LINE OP 

FLAG FIELD , UNUSED 

ARRAY NAME ADDRESS 

FORMAT NAME ADDRESS 
COMMAND/LINE OP CNTL BLK 
LINE OPERATOR IN PROGRESS 
ROWID # OF THE LAI ENTRY 
LAI ENTRY # 

COMMAND FLAG 

RESERVED 

ADDRESS OF CATALOG NAME FOR 
DATA SET APPLICATION oN 
ADDRESS OF LAI \ 
ADDRESS OF ROW IDS 7 
TOTAL ENTRIES IN LAI 

LIST PNL CURSOR CTL BLK 
ADDR OF THE NAME OF THE 
CATALOG NAME TABLE FOR DATA 
SET APPLICATION 

ADDR OF THE LONG MSG 
RESERVED UNUSED 

END OF LPPL 











=e S >. 


PCCB 


Entry Point: CPPLCSCB 


PCCB 
Offsets Type Length Name Description 
PANEL CURSOR CONTROL BLOCK (PCCB) 
0 (0) CHARACTER 16 PCCB 
0 (0) CHARACTER 4 PCCBVID VISUAL ID: 'PCCB' 
4 (4) FIXED 2 PCCBLEN LENGTH OF PCCB 
6 (6) FIXED 2 * RESERVED, UNUSED 
8 (8) ADDRESS 4  PCCBCFAD CURSOR FIELD ADDRESS 
12 (C) ADDRESS 4 PCCBCOAD CURSOR OFFSET ADDRESS 
16 (10) CHARACTER PCCBEND END OF PCCB 
PVT 
Entry Point: GDRBPVT 
PVT 
Offsets Type Length Name Description 
ISMF PROFILE VARIABLE TABLE (PVT) 

0 (0) CHARACTER 16 PVT 
0 (0) CHARACTER 4 PVTVID VISUAL ID CONTAINS 'PVT ' 
4 (4) FIXED 2 PVTLEN LENGTH OF PVT 
6 (6) FIXED 2 * RESERVED 
8 (8) ADDRESS 4 PVTL72 PTR TO VARS WITH LEN 72 
12 (C) ADDRESS 4 PpvVTL1 PTR TO VARS WITH LEN 1 
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PVTV 


Entry Point: PVTL72 (field PVTL72 in control block PVT—for structure P@MPVT72) 


PVTL1 (field PVTL1 in control block PVWT—for structure PGMPVT0O1) 


PVTV 


Offsets 


Description 


L eandfununedfesnandfunanelivevuvdheanamtpaaneth-avarcdpmemalnmantionnandsmatmmvedhantasdeunenthaamvetecenadpameatbanspadh enasdansndeamatamandoere natant paaendiuesandh-ammmtanedienamtaaadesssasdeedimndhancadtemadanmatiemrd sant amtirnaediesssatanasat-arndianamakerceadeansat-ennadierssdeamedcmnudpasemtamadicssnstiemendhaasthastandmadhasatnnmdhersndammadkcnunadpamadtmmsabaansushemadhcanapmmmdeerasdanambansedamndieenedamead 
SP NS ED CUED AE ED SURES GRRE SND ED ED SED NE NEED REE CES LES EET OLNEY GED TGS SERED CED GLEE GEREED CWNEE GUREED GUD GEES EEE GREED GUNES GERARD GENES GERD QUES GRE ERED GES GREED reer GED Gee EAD GEES INS ERE CUED GERD GED QED GED GEESE GHEED GREER GunnD GQRENY GENTE GHNEED GEE SURE) GERD ERED GLENS GEES GANIED GERD ONE? GREE Gwe HEE GamED Ghuw CEE ane 


[inne promnaleansandpetusandbamsvathmnnetieeaenclammadbasamdinamdbammrath esartmmaruuedemmdpumendl emaudivummaibanaratennalammattannarthamthrasssadhenanthamnedhsnnadeensmth-aaabsmmatimeadionsndiamuiaemadesdadinancdfmmundheundersamaiaaatescesstmandnasendinnadtumedhcmadh-andesaedkommadicreradieamndiaeneaiecansatkemandeanadpnamdamndiomandiarmadcpeatcaaied-anssathumedieeadh-mnaameadhernadeemamdanabagusleasndammantnanzeduasnnd 
a SA SET IN CEE SEND SOE SEED SETS GRAND GLUED SHLD VEN SUE GREENS GED SaNENY ROUND UND SAEED SEND AED GENES NN SOREN GAMES GENTE SUES GED GIES GERD SEND EE GSU TINS GORE GENER GREED URED GENES Gem SNES GEES GREED COREE GRE WATS GENET GUTS SERRE GENT RED GEE GD CUES GREED GREED GER RED CEE SD GEES Geen: GREED GENET GED SEED GD GHEE Gm ames GITER am 


72 
144 
216 
288 
360 
432 
504 
576 
648 
720 
792 
864 
936 

1008 
1080 
1152 
1224 
1296 
1368 
1440 


PVTV 


Offsets 


0 


0 
1 
2 
3 


(0) 
(0) 
(1) 
(2) 
(3) 


CHARACTER 1512 
CHARACTER 72 
CHARACTER 72 
CHARACTER V2 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER TZ 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER V2 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
CHARACTER 72 
Type Length 
CHARACTER 4 
CHARACTER 1 
CHARACTER 1 
CHARACTER 1 
CHARACTER 1 
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PGMPVT72 
APPFDE1 1 


APPFDE12 
APPFDE13 
APPFDE14 
APPFDE15 
APPFDE16 
APPFDE17 
APPFJOB1 
APPFJOB2 
APPFJOB3 
APPFJOB4 
APPFJOB5 
APPFJOB6 
APPFJOB7 
APPFDE21 
APPFDE22 
APPFDE23 
APPFDE24 
APPFDE25 
APPFDE26 
APPFDE27 
Name 
PGMPVTO1 
APPFLDED 
APPFLIMT 


APPFLTPT 
APPFLRFA 


PVT VARS WITH 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 


Description 

PVT VARS WITH 
LOGGING/ABEND 
LOGGING/ABEND 
LOGGING/ABEND 
LOGGING/ABEND 


LEN OF 72 
STATEMENT 


STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 
STATEMENT 


STATEMENT 


LEN OF 01 

CONTROL VARIABLE 
CONTROL VARIABLE 
CONTROL VARIABLE 
CONTROL VARIABLE 


\ 
ei 











SELB 


Entry Point: This control block and all control blocks addressed by it must be created by the external 


application that uses the service requiring the control block. 


When using the SELB, observe the requirements in the following table. 


Service Field Name ___ Field Value 


Using SELB 


DGTFARF1 SELBARNM Value pointed to by CPPLARNM 


SELBNP "N’ 
SELBNO 


SELB 
Offsets Type 


15-bit value set to X'1' 





Description 


( enelhemenalbavusedhsranetoumtbansesdlumeadh smncedlioeaathomasd ansedt-anevabasssedieresdamnadnamectamalbamedbensedt muted amber madkeanadladtiacamdimsadhcamdiamdostrcadh-sasaemadthanadescadknadhamlsanandl vasadkralamatkamnelsanadkeniadthnsnaddomnad-smadiaamatanadimandhnasnsediaarademdlommadhemnathanesdeandeematnmamtnenndtranataatadaadieranndtbeveaatmaadaadeumreditandoretateummdinatemmataseaedemraed 
ES NS SONS ENED GED SORRY CURLED SEED GOED SUEGS SEEEES GREED GERD ETD CREED GORD CDE GMD GERAD GEN GED SERGE OTT GED ED GNSS SAR ED ES SN STS GND GOED AMON GRE GED MES GED CR SRD SED GES GORD GEE ENED GNA GREED CURED GEEENS GENS GED GLE SIRES SEED QUES GOETEE SEED WEEERS GAMES GANS CHNOED GUNS GUAR) EE ERED GOREN GUD GELS MEE GUILD GREED GSE SEND GONE CON 


0 (0) CHARACTER 

0 (0) CHARACTER 

4 (4) FIXED 

6 (6) FIXED 

8 (8) CHARACTER 

16 (10) CHARACTER 

17 (11) CHARACTER 

18 (12) FIXED 

20 (14) BITSTRING 
i. ae 
eNece,  S.Stend 
Spelltes > Seca teds 

21 (15) CHARACTER 

24 (18) ADDRESS 

28 (1C) ADDRESS 

32 (20) ADDRESS 

36 (24) ADDRESS 

40 (28) CHARACTER 





—-N—--WONN FO 


FEE HW 


SELBLEN 
* 
SELBARNM 
SELBNP 

* 
SELBLNO 
SELBFLG1 
SELBKEEP 
SELBUSE 
SELBONE 
* 
SELBDBLO 
SELBCNDL 
SELBDBLI 
SELBRID 
SELBEND 





VISUAL ID: 'SELB' 

LENGTH OF SELB 

RESERVED, UNUSED 

ARRAY NAME 

DIRECTION OF SEARCH 
RESERVED, UNUSED 

NTH LINE TO BE RETRIEVED 
FLAG FIELD 

SAVE SEARCH CRITERIA 

USE OLD SEARCH CRITERIA 
USE NEW SEARCH CRITERIA 
RESERVED, UNUSED 

ADDR OF DABL FOR OUTPUT 
ADDRESS OF CONDITION LIST 
ADDR OF DABL FOR INPUT 
ADDR OF VAR TO PUT ROWID 
END OF SELB 
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SRVT 





Entry Point: GDRBSRVT 


SRVT 
Offsets Type Length Name Description 
6) (0) CHARACTER 112 SRVT 
0 (0) CHARACTER 8 SRVTHDR SRVT HEADER 
0 (0) CHARACTER 4 SRVTVID SRVT VISUAL ID IS 'SRVT' 
4 (4) FIXED 2 SRVTLEN LENGTH OF SRVT 
6 (6) FIXED 2 * UNUSED, RESERVED 
8 (8) ADDRESS 4 SRVTPRO1 PROLOG ENTRY POINT ADDRESS 
12 (C) ADDRESS 4 SRVTPRO2 PROLOG ENTRY POINT ADDRESS 
16 (10) ADDRESS 4 SRVTEPO1 EPILOG ENTRY POINT ADDRESS 
20 (14) ADDRESS 4 SRVTGMO1 GETMEM ENTRY POINT ADDRESS 
24 (18) ADDRESS 4 SRVTFMO1 FREEMEM ENTRY POINT ADDRESS 
28 (iC) ADDRESS 4 SRVTLDO1 LOAD ENTRY POINT ADDRESS 
32 (20) ADDRESS 4 SRVTDTO1 DELETE ENTRY POINT ADDRESS 
36 (24) ADDRESS 4 SRVTDVO1 DSN VERIFICATION ENTRY POINT 
ADR 
40 (28) ADDRESS 4 SRVTVVO1 VOL VERIFICATION ENTRY POINT 
ADR 
44 (2C) ADDRESS 4 SRVTWOO1 WORD PARSER ENTRY POINT 
ADDRESS 
48 (30) ADDRESS 4  SRVTARB1 ARRAY SERVICE INITIALIZATION 
52 (34) ADDRESS 4 SRVTARN1 ARRAY SERVICE TERMINATION 
56 (38) ADDRESS 4 SRVTFOB1 FORMAT SERVICE INITIALIZATION 
60 (3C) ADDRESS 4 SRVTFON1 FORMAT SERVICE TERMINATION 
64 (40) ADDRESS 4 SRVTASO1 RACROUTE SERVICE ROUTINE 
68 (44) ADDRESS 4 SRVTCDO1 CONVERSION SERVICE ROUTINE 
72 (48) ADDRESS 4 SRVTDAOO DATA ACQUISITION EPA 
76 (4C) ADDRESS 4  SRVTLGO1 LOG SERVICE ROUTINE EPA 
80 (50) ADDRESS 4 SRVTCCO1 SELECT FILTER VERIFICATION 
84 (54) ADDRESS 4 SRVTCTB1 COMMAND TABLE BEGIN 
88 (58) ADDRESS 4 SRVTCTE1 COMMAND TABLE END 
92 (5C) ADDRESS 4 SRVTCDO2 CONVERSION SERVICE ROUTINE 
96 (60) ADDRESS 4 SRVTCDO3 - CONVERSION SERVICE ROUTINE 
100 (64) ADDRESS 4 SRVTCDO4 CONVERSION SERVICE ROUTINE 
104 (68) ADDRESS 4 SRVTCDO5 CONVERSION SERVICE ROUTINE 
108 (6C) ADDRESS 4 SRVTCDQ1 CONVERSION TABLE QUERY ROUTINE 
Constants 
Length Type Value Name Description 


2 DECIMAL 18 SRVTCNT 
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Index 


ABE appendage 71 
abnormal-end appendage 
See ABE appendage 
access method routines, functions performed in I/O 
operations 63 
accessing VTOCs and VTOC indexes 42-60 
alias name 
of UCS images for JES2 225 
allocating DASD space 5 
allocation retrieval area 


format 144 
allocation retrieval list 
format 144 


altering DADSM processing 125 
alternate track 

assigning with ATLAS 83 
AM operand 

in DEBCHK macro 153 
APF (authorized program facility) requirements 18 
appendages 

ABE (abnormalend) 71 

CHE (channelend) 71 

entry points 71 

EOE (end of extent) 71 

listing in SYS1.PARMLIB_ 71 

naming convention 71 

PCI (program controlled interruption) 71 

PGFX (page fix) 94 

programming restrictions 71 

returns 71 

SIO (startI/O) 71 
ARVT (array service vector table) 335 
assigning alternate track with ATLAS 83-85 
ATLAS macro 

coding example 85 

how touse 85 

IOBSENS fields with 85 

operations performed 86 

return codes 86 

specification 83-85 

unit check with 85 

with track overflow option 84 

uthorized appendage list 71 
uthorized program facility 
See APF 








BALANCE operand (TRKCALC macro) 164, 166 


BFALN operand (DCB macro) 77 
BFTEK operand (DCB macro) 77 
bit maps 
of allocated DSCBs_ 14 
of allocated VIRs 14 
block ID 
setting in JFCB for high-speed positioning 
BSAM (basic sequential access method) 
defaulting buffer number 125 
BUFCB operand (DCB macro) 77 
buffer 
DASD data sets 
performance considerations with 
BUFNO 229 
selecting quantity with BUFNO 229 
lists 49 
entry format 46 
format 45-47 
function 45 
header format 45 
how created 45 
releasing 49 
releasing 49 
BUFL operand (DCB macro) 77 
BUFNO operand (DCB macro) 77 
defaulting in OPEN installation exit 
example (QSAM) 305 
selecting value for DASD data sets 229 
performance considerations 229 


CAMLST macro 
with RENAME operand 38-41 
with SCRATCH operand 33-37 
with SEARCH operand 29-31 
with SEEK operand 31-33 
catalogs 
dummy module 227 
CCW (channel command word) 69 
See also channel programs 
CENDA operand (DCB macro) 75 
channel-end appendage 
See CHE appendage 
channel programs 
appendages used with 71 
execution 68-69 
initiation 68-69 
related 71 
restrictions on modification 70 


Index 





149 
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translation, virtual addresses to real 
addresses 95-97 © 
CHE appendage 71 
checking the DEB (DEBCHK) 151-155 
checkpoint data set 
processed with EXCP macro 79 
CLCB (command/line operator control block) 335 
CLOSE macro 
used with EXCP macro 83 
used with XDAP macro 104 
codes 
returned with error message 298-303 
routing and descriptor 298 
command retry 72 
communication vector table (CVT) mapping macro 
See CVT mapping macro 
completion codes 
See also return codes 
following use of EXCP macro 93 
following use of XDAP macro 105 
CONH (conditional control block header) 336 
control blocks 
PIRL 161 
used with EXCP 
DCB 73-80 
DEB 92 
ECB 92 
IOB 88-91 
control password 116 
conversion 
of sector value for RPS devices 108 
routine, actual track address to relative track 
address 107 
register usage 107 
routine, relative track address to actual track 
address 106 
register usage 106 
return codes 107 
copy operation 
DASD volume 
indexed VTOC requirements 18 
nonindexed VTOC requirements 18 
copying 
DASD volumes 18 
CPPL (command processor parameter list) 337 
creating 
protected datasets 113 
CTAP (command table - application table) 338 
CTFU (command table - function table) 338 


CTPL (command table processor parameter list) 339 


CTVT (command table processor vector table) 340 
CVAF (common VTOC access facility) 
filter service 
control blocks required for 53 
reading sets of DSCBs with 52 
processing of GTF trace 61 
serialization 42 
volume identification to 42 
VTOC access macros 
CVAFDIR examples 259-270 
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CVAFFILT example 271-277 
CVAFSEQ example 277-292 
CVAFTST and CVAFDSM 
examples 292-296 
uses and syntax 231-258 
CVAF parameter list 
See CVPL 
CVAFDIR macro 
examples 259-270 
how to use 47 
parameters 232, 237 
return codes 238 
syntax 231 
uses 231 
CVAFDSM macro 
example 292-296 
how touse 59 
parameters 239-244 
return codes 244 
syntax 239 
uses 239 
CVAFFILT macro 
control block address resolution 245-246 
examples 271-277 
filter criteria list 
entry format 56 
header format 54 
how touse 52 
invocation sequences 
example 57 
parameters 246-249 
partially qualified names 
examples 250 
RESUME capability 52 
return codes 249 
syntax 245 
uses 245 
CVAFSEQ macro 
examples 277-292 
how touse 50 
parameters 251-255 
return codes 256 
syntax 251 
uses 251 
CVAFTST macro 
example 292-296 
return codes 258 
syntax 257 
uses 257 
CVFCTN field of CVPL 
contents 45 
definitions 45 
CVPL (CVAF parameter list) 
format 44 
function 43-44 
when created 43 
CVSTAT codes 298 
CVT (communication vector table) mapping 
macro 129 








ia ; 
’ j 
% f 
= 7, 
: a 





DAB (data attrubute block) 341 
DABL (data attribute block list) 342 
DADSM 
allocate routine 5 
return codes 181 
overview 1 
postprocessing exit 
when given control 125 
pre/postprocessing exits 125 
data passed from DADSM_ 125 
format-1 DSCB passed by IGGPREOO 
operating environment 125 
parameter list (EPL) 125 
register contents 125 
rejecting a DADSM request 125 
return codes from IGGPREOO 125 
system control block addresses 125 
preprocessing exit 
altering DADSM processing 125 
when given control 125 
DASD (direct access storage devices) 
obtaining free space 
LSPACE macro 20-29 
reading and writing to 
XDAP macro 99-103 
DASD calculation (DCS) exits 
See DCS pre/postcalculation exits 
data control block 
See DCB (data control block) 
data extent block (DEB) 
See DEB 
data management 
ABEND installation exit 125 
modifying 125 
parameter list (OAIXL) 125 
register contents 125 
return codes 125 
data set 
security 
See password protection 
data set control block (DSCB) 
See DSCB 
DCB macro 
used with EXCP macro 68, 73-80 
used with XDAP macro 100 
DCB OPEN installation exit 125 
description 125 
example 305 


example, defaulting buffer number (QSAM) 305 


example, requesting partial release 305 


125 


example, updating secondary space data 305 


operating environment 125 

parameter list (OIEXL) 125 

register contents 125 

return codes 125 

when executed 125 
DCBDIRCT field of DCB 76 





DCBFDAD field, maintaining 76 
DCBIFLGS field of DCB, permanent I/O error 
indicators 70 
DCBOFLGS field of DCB, meanings of bit 
settings 81-82, 83 
DCBTRBAL field, maintaining 78 
DCS (DASD calculation services) 
exit routines 125 
overview 125 
parameter list (DCSIEPL) 125 
register contents 125 
postcalculation exit 
overview 125 
return codes 125 
precalculation exit 
overview 125 
return codes 125 
DCSIEPL (DCS pre/postcalculation exit parameter 
list) 125 
DD operand (TRKCALC macro) 165, 167 
DDNAME operand (DCB macro) 74 
DDR (dynamic device reconfiguration), repositioning 
tape datasets 74 
DEB (data extent block) 
fields 92 
obtaining 42 
used with EXCP macro 68 
validating with DEBCHK 151-155 
DEBCHK macro 
functions of 151-155 
register contents 154 
return codes 155 
specification 152-155 
defaulting buffer number 
for BSAM_ 125 
for QSAM_ 125 
in OPEN installation exit 
example for QSAM 305 
defective track 
See assigning alternate track with ATLAS 
define extent CCW 
in EXCP processing 69 
deleting 
a data set 
coding example 35 
macro instructions for 33 
when volume not mounted 34 
DEMOUNT parameter (MSGDISP macro) 191 
DEN operand (DCB macro) 79 
DEQ macro 
at demount facility 147 
DEVD operand (DCB macro) 77-79 
device characteristics 129-135 
device dependent parameters in DCB 77-80 
DEVTAB operand (TRKCALC macro) 164, 166 
DEVTYPE macro 
EXECUTE form 
specification 136 
for RPS devices 130 
list form 
specification 136 
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output from 130-135 obtain count of datasets 323 


return codes 133 obtain input information from the screen area a 
specification 130-131 image 328 i 
DFP ISMF common services 330 place information in the ISPF log 317 
control blocks available to external applications position current row pointer at top of list 322 
ARVT (array service vector table) 335 process commands 326 
CLCB (command/line operator control refresh the screen image area from the data set 
block) 335 list array 329 
CONH 336 update data set list array 324 
CONH (conditional control block verify commands 325 
header) 336 volume serial number syntax verification 319 
CPPL (command processor parameter word finder 320 
list) 337 input register contents 307 
CTAP (command table - application input requirements 307 
table) 338 linkage and error handling 307 
CTFU (command table - function table) 338 output register contents 308 
CTPL (command table processor parameter overview 307 
list) 339 parameter lists 308 
CTVT (command table processor vector DSCB (data set control block) 
table) 340 described 3 
DAB (data attribute block) 341 format-0 3 
DABL (data attribute block list) 342 format-1 4 
ERNT (error table entries) 343 format-1 not found user exit 125 
ERTB (ISMF error table) 343 format-2 4 
ET (ISMF environment table) 344 format-3 4 
FOVT (format service vector table) 344 format-4 5 
GDRB (ISMF global data repository format-5 5 
block) 345 format-6 5 
IMNT (IMTT entries) 346 reading from VTOC by absolute device address 
IMTT (ISMF inter module trace table) 345 coding example 32 Pe 
introduction 335 macro specifications 31 q 
LOGB (ISMF log buffer) 346 return codes 33 ue? 
LPAP (line operator table - application reading from VTOC by data set name 
table) 347 - coding example 30 
LPCB (list panel cursor control block) 347 macro specifications 29 
LPPL (line operator processor parameter return codes 31 
list) 348 DSECT expansions 
PCCB (panel cursor control block) 349 See CVT, IEFJFCBN, IEFUCBOB, TRKCALC 
PVT (ISMF profile variable table) 349 DSN order 
PVTV (ISMF profile variable table initiating access to DSNs, DSCBs 50 
variables) 350 DSORG operand (DCB macro) 76 
SELB (select block) 351 dynamic device reconfiguration 
SRVT (ISMF common service routine vector See DDR 
table) 352 
functions 
IGBDISOO 330 
messages available to external applications 331 || 
DFP ISMF services 


control blocks 
locating 308 
error logging 309 
functions 
data set name syntax verification 311 


ECB (event control block) 
used with EXCP macro 68, 92 
used with XDAP macro 104 
end-of-extent appendage 


decrement use count 310 See ee appendage 
enable valid commands 327 end-of-volume 
See EOV macro 


find an entry in the data set list array 321 
freememory 314 EODAD operand (DCB macro) 76 


i EOE appendage 71 
free storage and exit 313 
get storage 315 EOEA operand (DCB macro) 74 


EOV macro 
load a module 316 
obtain automatic data area 318 and Format-1 DSCB not found § 125 
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used with EXCP macro 81-83 
used with XDAP macro 104 
ERNT (error table entries) 343 
error 
EXCP I/O 
recovery procedures 70 
VTOC 
processing 60 
recovering from system or user errors 60 
error messages 
See messages, CVAF VTOC error 
ERTB (ISMF error table) 343 
ET (ISMF environment table) 344 
event control block (ECB) 
See ECB 
examples 
of CVAFDIR macro 259-270 
of CVAFFILT macro 271-277 
of CVAFSEQ macro 277-292 
of CVAFTST and CVAFDSM macros 292-296 
of OPEN installation exit module 305 
EXCP (execute channel program) 
ABE appendage 71 
building list of fixed data areas 94 
channel programs 
appendage entry points 71 
appendage programming restrictions 71 
appendage register usage 71 
appendage returns 71 
appendages used with 71 
authorized appendage list 71 
completion processing 70 
execution 68-69 
I/O error handling 70 
including appendages in the system 71 
initiation 68-69 
modifying 70 
programming considerations 72-73 
translation by I/O supervisor 95 
CHE appendage 71 
control blocks used with 


DCB 68 
DEB 68 
ECB 68 
IOB_ 67 


EOE appendage 71 | 
IDAWs (indirect addressing words) 66 
in V=R address space 66 
PCI appendage 71 
requirements 67 
channel program 67 
control blocks 67 
SIO appendage 71 
EXCP macro 
advantages of using 64 
control blocks used with 
DCB 73-80 
DEB 92 
ECB 92 
IOB_ 89-91 
in problem programs 65 
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in real storage 92 
in system control programs 64 
macro specification 81 
macros used with 
ATLAS 83 
CLOSE 83 
EOV 81-83 
OPEN 80-81 
multivolume data set requirement 80 
used with WAIT macro 65 
EXCPVR macro 92-94 
executing channel programs 
in problem programs 65 
in real storage 92 
in system control programs 64 
exit routine 
See also DADSM pre/ postprocessing exits 
See also data management ABEND installation exit 
See also DCB OPEN installation exit 
See also DCS pre/postcalculation exits 
See also format-1 DSCB not found 
See also OPEN/EOV IBM standard labeled tape 
security verification exit 
See also OPEN/EOV nonspecific tape mount 
request user exit 
functions possible 125 
EXLST operand (DCB macro) 76 
expiration date 
overriding 35 


| 


FCB (forms control buffer) image 
adding image to SYS1.IMAGELIB 219-221 
default image 
3262 printer 217 
4245 printer 217 
4248 printer 217 
in SYS1.IMAGELIB) 217-223 
JES2 support 225 
retrieving image from SYS1.IMAGELIB 222-223 
FCL (filter criteria list) 53 
entry format 56 
header format 54 
filter criteria list (FCL) 
See FCL 
fixing data areas with EXCPVR 92 
format 
of allocation retrieval area 144 
of allocation retrieval list 144 
of buffer list entry 46-47 
of buffer list header 45 
of CVPL (CVAF parameter list) 44 
of DADSM pre/ postprocessing exit parameter 


list 125 
of DCS pre/postcalculation exit parameter 
list 125 


of LSPACE data return area 27 
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of LSPACE message return area 27 
of LSPACE parameter list 24 
of OIEXL (OPEN installation exit parameter 
list) 125 
of VIER 10 
of VIER index entries 11 
of VTOC maps 15 
format 0-6 DSCB 3 
format-1 DSCB 
reading from VTOC 29 
format-1 DSCB not found 
installation exit IFGOEXOA) 125 
parameter list 125 
register contents 125 
return codes 125 
forms control buffer image 
See FCB image 
FOVT (format service vector table) 344 
free space 
on DASD volume 
obtaining with LSPACE macro 20-29 
FUNCTN operand (TRKCALC macro) 162-170 


GDRB (ISMF global data repository block) 345 
GEN operand (MSGDISP macro) 197 
GTF trace of CVAF processing 

See CVPL 


[a] 


high-speed 3480 positioning 149 


[1] 


I/O devices 
characteristics 129 : 
IDAL (indirect data address list) 95-97 
IDAW (indirect addressing word) 
requirements 66 
IEAAPPO0, authorized appendage list 71 
IEBUPDTE program 
SYS1.PARMLIB 
use in listing appendages in 71 
IECPCNVT (relative track address to actual track 
address conversion routine) 106 
IECPRLTV (actual track address to relative track 
address conversion routine) 107 
IECOSCR1 (sector conversion routine) 108 
IEFJFCBN macro 128 
IEFUCBOB macro 128 
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TEHATLAS program 85 : 
IEHLIST program 61 | fo™ 
IEPL (DADSM pre/postprocessing exit parameter \ | 
list) 125 
IFGOEXOA program 
See format-1 DSCB not found 
IFGOEXOB program 
See DCB OPEN installation exit 
IFG0199I program 
See data management ABEND installation exit 
IGBDCSX1 | 
See DCS precalculation exit 
IGBDCSX2 
See DCS postcalculation exit 
IGGPOST0 program 
See DADSM pre/ postprocessing exits 
IGGPREO00 program 
See DADSM pre/ postprocessing exits 
IGGUCSIT macro 213 
THAARL macro 
specification 143 
IMNT (IMTT entries) 346 
IMSK operand (DCB macro) 76 
IMTT (ISMF inter module trace table) 345 
indexed VTOC 
compared to nonindexed 16 
initiating access to DSCBs_ 50 
indexing feature for 3211 226 
indirect addressing word (IDAW) 


See IDAW ok, 
indirect data address list (IDAL) a 
See IDAL ee 


initializing DASD volumes 18 
interruption handling procedures 70 
IOB (input/output block) 

chain modification 161 

fields with EXCP macro 89-91 

fields with XDAP macro 105 

used with EXCP macro 67 
IOBAD operand (DCB macro) 77 
IOBSENS fields with ATLAS macro 85 


JES2 
Printer support 225-226 
JFCB (job file control block) 
See also RDJFCB macro 
macros used with 
TIHAARL $143 
OPEN 148-149 
RDJFCB 137-140 
mapping macro 128 
modifying 125, 136-150 
precautions 137 
job file control block (JFCB) 
See JFCB 











DCB 73-80 
ms. | K| DEBCHK 152-155 
( DEVTYPE 129-135 


EOV 
K operand (TRKCALC macro) 165, 166 and Format-1 DSCB not found 125 
KEYLEN operand (DCB macro) 79 used with EXCP macro 81-83 
used with XDAP macro 104 
EXCP 81 


EXCPVR 92-94 
IEFJFCBN 128 
: IEFUCBOB- 128 
LSPACE 20-29 
MSGDISP_ 184-201 
OBTAIN 29-33 
OPEN 
and Format-1 DSCB not found 125 
for JFCB 149 
for modified JFCB 148 
used with EXCP macro 80-81 
PARTREL 170-174 
PROTECT 116-124 
PURGE 156 
RDJFCB 136-140 
REALLOC 174-183 
RENAME 38-41 
RESTORE 156 
specification 161 
SCRATCH 33 
TRKCALC 162-170 
used with XDAP macro 100-101 


LABEL operand (DD statement) 
password protected data set 112,113 
library character set modules 203 
LIST operand 
CVT macro 129 
IEFJFCBN macro 128 
IEFUCBOB macro 128 
locate record CCW 
in EXCP processing 69 
LOGB (ISMF log buffer) 346 
LPAP (line operator table - application table) 347 
LPCB (list panel cursor control block) 347 
LPPL (line operator processor parameter list) 348 
LSPACE macro 20-29 
coding example 
list and execute forms 29 
using data return area 28 
using message return area 28 
data return area 





: es XDAP 99-103 
ormat maintaining 124 
mais return area See also PROTECT macro 
bee 27 PASSWORD dataset 116-124 
parameter list VTOC (volume table of contents) 19-41 
format 24 


mapping macros 
CVT 129 
IEFJFCBN 128 
IEFUCBOB 128 


return codes 25 


| | maps of allocated space 
for cylinders and tracks 12 
for DSCBs_ 15 
MACRF=(E) operand (DCB macro) 74 for VIRs_ 14 
macros, data management MAXSIZE operand (TRKCALC macro) 164, 166 
See also CVAFDIR macro messages | 
See also CVAFDSM macro CVAF VTOC error 
See also CVAFFILT macro descriptor codes 298 
See also CVAFSEQ macro programmer response 298 
See also CVAFTST macro return codes 298-303 
ATLAS 83 routing codes 298 
CAMLST system action 297 
with RENAME operand 38-41 text and explanation 297 
with SCRATCH operand 33-37 when issued 297 
with SEARCH operand 29-31 MF operand 
with SEEK operand 31-33 DEBCHK macro 155 
CLOSE TRKCALC macro’ 165-167 
used with EXCP macro 83 MODE operand 
one used with XDAP macro 104 EOV macro 82 
f 7 CVAF (VTOC access) MODE operand (DCB macro) 80 
hice” uses 42 modifying 
CVT 129 channel program during execution 70 
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IOB chain 161 
JFCB 136, 150 
in OPEN installation exit 125 
MOUNT operand (MSGDISP macro) 184 
MSGDISP macro 184 | 
displaying a demount message 191 
displaying a mount message 184 
displaying a ready message 189 
displaying a verify message 187 
providing the full range of display options 197 
resetting the message display 194 
return codes 200 
multivolume data set 
processing with EXCP macro 80 


name 

VTOC index 8 
nonindexed VTOC 

compared to indexed 16 
nonpageable address space, V=V 69 
NOPWREAD protection-mode indicator 116 
NOWRITE protection-mode indicator 116 


[| 


OAIXL (data management ABEND installation exit 
parameter list) 125 
OBTAIN macro 29-31 
obtaining a sector number (RPS devices) 108 
OIEXL (OPEN installation exit parameter list) 125 
OPEN installation exit 
See DCB OPEN installation exit 
OPEN macro 
and DEQ at demount facility 147 
and Format-1 DSCB not found 125 
getting controlfrom 125 
TYPE=J 
example 141 
invoking 147 
specification 149 
used with EXCP macro 
dummy data set restriction 80 
procedures performed 80 
used with XDAP macro 101 
with modified JFCB 148 
open processing 
after IFGOEXOB gets control 125 
and OPEN installation exit 125 
before IFGOEXOB gets control 125 
opening a VTOC 
restriction on changing contents 140 
OPENJ (OPEN, TYPE=J) macro 
specification 148 
OPTCD=Z operand (DCB macro) 76 
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OUTINX operand (OPEN macro) 76 


output data set | a 
maintaining DCBBLKCT field 74 WY 


[P| 


page boundary 95 
page-fix 
appendage 
See PGFX appendage 
list processing 94 
pageable address space, V=R 66 
parameter list 
See CVPL 
See DADSM pre/ postprocessing exits 
See data management ABEND installation exit 
See DCB OPEN installation exit 
See DCS pre/postcalculation exits 
See format-1 DSCB not found installation exit 
partial release via JFCB modification 125 
in OPEN installation exit 
example 305 
PARTREL macro 170-174 
return codes 174 
password 
See also PROTECT macro 
control 116 
counter maintenance 115 | 
data set concatenation 115 See” 
deleting or renaming a protected dataset 115 
parameter list 118 
ADD arecord 118 
DELETE arecord 122 
LIST arecord 123 
REPLACE arecord 120 
protecting datasets 111-124 
protecting tape datasets 114 
protecting VTOC indexes 18 
protection mode indicator 116 
record 113 
protection mode indicator 113 
secondary 116 
standard label restriction 112 
terminating protection 114 
volume switching 115 
PASSWORD data set 
characteristics 116 
creating 113 
protected data set recordsin 116 
requirements 113 
PCCB (panel cursor control block) 349 
PCI appendage 71 
PCI operand (DCB macro) 74 
PCIA operand (DCB macro) 74 
PGFX appendage 94 7 
physical sequential access, initiating 51 Af ™ 
PIRL (purged I/O restore list) 


use in restoring I/O requests 161 




















posting completion code in ECB 
following use of EXCP macro 92 
following use of XDAP macro 104 
postprocessing 
See DADSM pre/ postprocessing exits 


PREFIX operand (IEFUCBOB macro) 128 


preprocessing 
See DADSM pre/ postprocessing exits 
printer image 
See UCS image 
program controlled interruption appendage 
See PCI appendage 
PROTECT macro 
See also password 
parameter list 122 
ADD function 118 
DELETE function 122 
LIST function 123 
REPLACE function 120 
protection mode indicator 116 
return codes 124 
syntax 117 


use with PASSWORD dataset 111-123 


protecting 
VTOC 
with RACF 17 
VTOC index 
with passwords 18 
with RACF 17 
PRTSP operand (DCB macro) 80 
PURGE macro 
adding to macro library 156 
definition 156 
parameter list 158 
return codes 160 
specification 158 
purged I/O restore list 
See PIRL 
PVT (ISMF profile variable table) 349 


PVTV (ISMF profile variable table variables) 350 
PWREAD protection-mode indicator 116 
PWWRITE protection-mode indicator 116 
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QSAM (queued sequential access method) 
defaulting buffer number 125 


[LR 


R operand (TRKCALC macro) 165, 166 
RACF 
protecting VTOCs and VTOC indexes 
renaming adataset 38 
scratching a dataset 34 
RDJFCB 





17 








retrieving allocation information 143 
RDJFCB macro 
allocation retrieval area 
format 144 
allocation retrieval list 
format 144 
coding example 138 
common coding errors 139 
description 137 


exit list entry for 
type '07' 139 
type '13' 142 


invoking DEQ at demount 147 
retrieving allocation information 
coding example 145 
return codes 139 
security 140 
specification 137 
use by authorized programs 141 
with MSS virtual volumes 140 
RDY operand (MSGDISP macro) 189 
reading 
and modifying a JFCB 136-140 
data from index maps 49 
DSCBs 
directly by dataset name 48 
directly by DSCB location 48 
sequentially 50 
VIRs 48-49 
reading sets of DSCBs 
with CVAF filter service 52 
READPSWD module 113 
REALLOC macro 174-183 
return codes 181 
RECFM operand (DCB macro) 77 
recovering 
fromerrors 60 
from permanent DASD I/O error 
See ATLAS macro 
register 
contents at return from DCB OPEN exit 125 
conventions for appendages 71 
usage by conversion routines 
actual to relative routine 107 
relative to actual routine 106 
usage by CVAF routines 43 
usage by I/O supervisor 71 


REGSAVE operand (TRKCALC macro) 165, 167 


related 
channel program 71 
requests 71 
releasing DASD space 5 


REMOVE operand (TRKCALC macro) 164, 166 


RENAME macro 
dummy module 227 
return codes 40 
specification 38 
renaming a data set 
coding example 39 
macro specification 38 
with password protection 41 


Index 
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WRITE protection mode indicator 41 
REPOS operand (DCB macro) 74 
requesting partial release via JFCB modification 
requirements 

for APF 18 

for DASD copy, restore, operations 

indexed VTOC 18 

nonindexed VTOC: 18 
RESET operand (MSGDISP macro) 194 
Resource Access Control Facility 

See RACF 
RESTORE macro 

adding to macro library 156 

definition 156 

specification 161 
restore operation 

DASD volume 

indexed VTOC requirements 18 
nonindexed VTOC requirements 18 
restoring DASD volumes 18 
restoring iob chain 161 
restrictions 

when scratching, renaming, allocating 16 
return codes 

ATLAS macro 86 

CVAFDIR macro 238 

CVAFDSM macro 244 

CVAFFILT macro 249 

CVAFSEQ macro 256 

CVAFTST macro 258 

DEBCHK macro 155 

DEVTYPE macro 133 

from DADSM allocation 181 

from DADSM exits 125 

from data management ABEND exit 125 

from DCB OPEN exit 125 

from DCS exits 125 

from format-1 DSCB not found exit 125 

from IECPCNVT convert routine 107 

LSPACE macro 25 

MSGDISP macro 200 

OBTAIN macro 


when reading from VTOC by absolute device 


address 33 
when reading from VTOC by data set 
name 31 
PARTREL macro 174 
RDJFCB macro 139 
REALLOC macro. 181 
RENAME macro 40 
SCRATCH macro 36 
TRKCALC macro 169 
with CVAF VTOC error message 298-303 
RKDD operand (TRKCALC macro) 165, 166 
RPS (rotational position sensing) 
devices 
used with XDAP macro 108 
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SCRATCH macro 
coding example 35 
dummy module 227 
general description 33 
return codes 36 
status codes 37 
scratching a data set 
when volume not mounted 34 
secondary 
passwords 116 
space data 
updating in OPEN installation exit 125 
updating in OPEN installation exit, 
example 305 
sector, address in XDAP macro 
specification 102 
with RPS devices 108 


securing 
a VTOC 
with passwords 18 
with RACF 17 
a VTOC index 
See also protecting a VTOC index 
with RACF 17 
seek CCW 


in EXCP processing 69 
SELB (select block) 351 
serialization, CVAF 42 
SIO appendage 71 
for EXCPVR 94 
SIOA operand (DCB macro) 74 
space map 
of allocated cylinders and tracks 12 
of allocated DSCBs_ 12 
of allocated VIRs 12 
SRVT (ISMF common service routine vector 
table) 352 
SSCH (start subchannel) instruction 
how used inI/O process 64 
when issued by IOS 69 
STACK operand (DCB macro) 80 
stand-alone seek 69 
standard label restriction, password data sets 112 
start-I/O appendage 
See SIO appendage 
start subchannel instruction 
See SSCH 
status codes 
SCRATCH macro 37 
system control blocks 125 
mapping macros for 
CVT 129 
JFCB (IEFJFCBN) 128 
UCB (IEFUCBOB) 128 
system macro instructions 127 
SYS1.IMAGELIB data set 
adding a UCS image to 204 

















maintaining 203 
UCS image tables in 209 
UCS imagesin 204 


tape volumes 
DEQ at demount facility 147 
testing fora VTOC index 257 
trace of CVAF processing 61 
track 
assigning an alternate 
with ATLAS 83 
calculating capacity 162-170 
translation of channel program 
by I/O supervisor 
in V=R address space 95 
in V=V address space 69 
in your own program 95 


TRKBAL operand (TRKCALC macro) 162-163 
example 169 

TRKCALC macro 162-170 
return codes 169 

TRKCAP operand (TRKCALC macro) 163-164 


example 169 
TRTCH operand (DCB macro) 79 
TYPE operand 
DEBCHK macro 152 
in OPEN macro 148 
TRKCALC macro 164, 166 
examples 169 
TYPE=J (OPEN macro) 148 


UCB (unit control block) 
getting information from 
See DEVTYPE macro 
mapping macro 131 
operand of TRKCALC macro 164, 166 
UCS (universal character set) 
image 
adding to SYS1.IMAGELIB 204 
examples of adding to SYS1.IMAGELIB 206 
for JES2 225 
verifying 215-217 
image table 
adding aliases 213 
adding image names 213 
contents 211 
entry format 209 
examples of addingto 216 
modifying entries 213 
structure 209 
unit check with ATLAS macro 85 
unit control block (UCB) 





See UCB 
universal character set (UCS) 
See UCS 
updating secondary space data 
in OPEN installation exit 125 
example 305 
user exit routine 
See exit routine 


V=R address space 

EXCP operations 66 
V=V address space 69 
validating the DEB (DEBCHK) 


151-155 


VERIFY operand (MSGDISP macro) 187 


VIER (VTOC index entry record) 
characteristics 9 
contents of fields 9 
format 10 
function 8 
how chained together 12 
how to find a format-1 DSCB 12 
special cases 12 
index entry 
format 11 
when created 11 
VIR (VTOC index record) 
kinds 8 
length 8 
virtual IDAW (indirect addressing word) 
VIXM (VTOC index map) 
bit maps 
of allocated DSCBs_ 14 
of allocated VIRs 14 
format 15 
function 14 
maps of allocated space 
for VIRs 14 
VMDS (VTOC map of DSCBs) 
format 15 
maps of allocated space 
function 15 
volume 
identification to CVAF 42 
switching 141 
table of contents 
See VTOC 
VPSM (VTOC pack space map) 
bit maps 
of allocated cylinders and tracks 
description 12 
format 15 
function 12 
space map 
of allocated DSCBs 12 
of allocated VIRs 12 
VTOC (volume table of contents) 


66 


12 


Index 
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access macros 


See CVAFDIR macro |x| —_ 
See CVAFDSM macro Ke 4 
See CVAFFILT macro al 
See CVAFSEQ macro XDAP 
See CVAFTST Macro channel program 105 

creating 17 macro 


description 1 


CLOSE macro used with 104 


example 8 control blocks used with 104 

how to locate 1 DCB macro used with 100 

index EOV macro used with 104 
contents 8 OPEN macro used with 101 


creating 17 

description 8 

how to list 61 

name 8 

password protection 18 
protecting with RACF 17 


requirements 100-101 
specification 101-103 
XENDA operand (DCB macro) 75 


relationship to VTOC 9 Numerics 
structure 9 

testing f 257 

ener 1403 printer 


index entry record (VIER) 


JES2 support 225 


See VIER ort . 
index map (VIXM) ne (indirect addressing word) 66 
See VIXM 
idee pce (VIR) JES2 support 226 
See VIR output from DEVTYPE 134 


initializing and maintaining 17 
maintaining 
description 1 
index 19, 33 
using OBTAIN macro 29-33 
using RENAME macro 38-41 
using SCRATCH macro 33-37 
map of DSCBs (VMDS) 


3211 printer 

indexing feature 226 

JES2 support 226 
3262 Model 5 printer 

default FCB image 217 

UCS image table for 209, 212 
3480 tape drive 

high-speed positioning 149 

output from DEVTYPE macro 134 


eae 3800 printer 
sages heise Ee) ; output from DEVTYPE macro 134 
protecting 4245 printer | 
with RACF 17 default FCBimage 217 
output from DEVTYPE macro 134 
UCS image table 209 
4248 printer 
default FCB image 217 
UCS image table 209 
WAIT macro 
used with EXCP macro 65 
writing 
DSCBs 49 
VIRs 49 
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